From 7a58c973998d8f8e90aeda5a25c9351a8c38de18 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Thu, 1 Aug 2019 15:05:31 -0400
Subject: [PATCH 01/65] ENH: Restore diffusion derivatives

---
 mkdocs.yml                                    |   1 +
 .../05-diffusion-derivatives.md               | 467 ++++++++++++++++++
 2 files changed, 468 insertions(+)
 create mode 100644 src/05-derivatives/05-diffusion-derivatives.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 88fa7df3..efea7e48 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,6 +31,7 @@ nav:
         - Introduction: 05-derivatives/01-introduction.md
         - Common data types: 05-derivatives/02-common-data-types.md
         - Imaging data types: 05-derivatives/03-imaging.md
+        - Diffusion derivatives: 05-derivatives/05-diffusion-derivatives.md
       - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md
       - Extending the BIDS specification: 07-extensions.md
       - Appendix:
diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
new file mode 100644
index 00000000..2c08e86e
--- /dev/null
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -0,0 +1,467 @@
+# Diffusion derivatives
+
+## Preprocessed diffusion weighted images
+
+Multiple different versions of preprocessing can be stored for the same source
+data. To distinguish them from each other, the `desc` filename keyword can be
+used. Details of preprocessing performed for each variation of the processing
+should be included in the pipeline documentation.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
+            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
+            <source_keywords>[_space-<space>][_desc-<label>]_dwi.json
+```
+
+The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
+see [Common Data Types](02-common-data-types.md)), and if present can be used to
+store information about what preprocessing options were used (for example
+whether denoising was performed, corrections applied for field inhomogeneity /
+gradient non-linearity / subject motion / eddy currents, intensity normalization was
+performed, etc.).
+
+Additional reserved JSON metadata fields:
+
+| **Key name**                   | **Description**                                                                                                              |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| Denoising                      | OPTIONAL. String. Denoising method                                                                                           |
+| MotionCorrection               | OPTIONAL. Boolean. Motion correction                                                                                         |
+| EddyCurrentCorrection          | OPTIONAL. Boolean. Eddy currents corrections                                                                                 |
+| IntensityNormalizationMethod   | OPTIONAL. String. Method (if any) used for intensity normalization                                                           |
+| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distortions arising from magnetic field inhomogeneity                            |
+| GradientNonLinearityCorrection | OPTIONAL. String. Correction for non-linear gradients; allowed values: `none`, `geometry`, `gradients`, `geometry&gradients` |
+
+## Diffusion Models (and input parameters)
+
+Diffusion MRI can be modeled using various paradigms to extract a more easily
+understandable representation of the diffusion process and the underlying
+structure. To do so, parameters might be needed to control how the signal is fit
+to the model. Those parameters are called **input parameters** in the following.
+Once the model is fit, the resulting representation can be saved using a number
+of values per voxel. Those values will be called **output** or **estimated
+parameters** in the following.
+
+**Estimated parameters** are saved as NIFTI files (see section Models for the
+expected content of each model), and **input parameters** are saved in the
+sidecar JSON file.
+
+The following is a general example of naming convention:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
+```
+
+The following models are codified and should be used in the `model-<label>`
+field. If a new model is used, common sense should be used to derive a name
+following the BIDS standard, and should ideally be integrated in a follow-up
+version of the specification.
+
+| Model label | Name & citation                                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DTI`       | Diffusion tensor imaging (Basser et al. 1994)                                                  | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>; the 6 unique parameters of the diffusion tensor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `DKI`       | Diffusion kurtosis imaging (Jensen et al., 2005)                                               | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>; Where D is the diffusion tensor and W is the kurtosis tensor.                                                                                                                                                                                                                                                                     |
+| `WMTI`      | White matter tract integrity (Fieremans et al., 2011)                                          | 4D image with D<sub>xx</sub>, D<sub>xy</sub>, D<sub>xz</sub>, D<sub>yy</sub>, D<sub>yz</sub>, D<sub>zz</sub>, W<sub>xxxx</sub>, W<sub>yyyy</sub>, W<sub>zzzz</sub>, W<sub>xxxy</sub>, W<sub>xxxz</sub>, W<sub>xyyy</sub>, W<sub>yyyz</sub>, W<sub>xzzz</sub>, W<sub>yzzz</sub>, W<sub>xxyy</sub>, W<sub>xxzz</sub>, W<sub>yyzz</sub>, W<sub>xxyz</sub>, W<sub>xyyz</sub>, W<sub>xyzz</sub>, Dh<sub>xx</sub>, Dh<sub>xy</sub>, Dh<sub>xz</sub>, Dh<sub>yy</sub>, Dh<sub>yz</sub>, Dh<sub>zz</sub>, Dr<sub>xx</sub>, Dr<sub>xy</sub>, Dr<sub>xz</sub>, Dr<sub>yy</sub>, Dr<sub>yz</sub>, Dr<sub>zz</sub>, AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
+| `CSD`       | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009)             | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `NODDI`     | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015)   | Three 3D images, with <parameter> equal to {`ICVF`,`OD`,`ISOVF`}: ICVF is the “intracellular volume fraction” (also known as NDI); OD is the “orientation dispersion” (the variance of the Bingham; also known as ODI); ISOVF is the isotropic component volume fraction (also known as IVF). Additionally a vector-valued map with the parameter name "`direction`" may provide the XYZ direction of the estimated fibre orientation.                                                                                                                                                                                                                                                                                        |
+| `DSI`       | Diffusion Spectrum Imaging (Wedeen et al. 2008; Paquette et al 2017)                           | DSI is generally used to compute the diffusion ODF (Orientation Distribution Function). No parameters are generally returned, but an ODF can be saved as a map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `CSA`       | Constant solid angle (Aganj et al. 2010)                                                       | 4D image with SH coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the side-car)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `SHORE`     | Simple Harmonic Oscillator based Reconstruction and Estimation. (Ozarslan et al. 2008)         | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `MAPMRI`    | Mean Apparent Propagator MRI. (Ozarslan, 2013)                                                 | 4D image with basis coefficients depending on choice of basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `FORECAST`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors. (Zuchelli et al. 2017) | 4D image with SH coefficients.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `fwDTI`     | Free water DTI (Hoy et al. 2014)                                                               | One 4D image with parameter name "`tensor`", containing 6 volumes in the order Dc<sub>xx</sub>, Dc<sub>xy</sub>, Dc<sub>xz</sub>, Dc<sub>yy</sub>, Dc<sub>yz</sub>, Dc<sub>zz</sub>, where Dc is the fw-corrected diffusion tensor in each voxel; one 3D image with parameter name "`FWF`" corresponding to the free water fraction in each voxel. .                                                                                                                                                                                                                                                                                                                                                                          |
+| `BedpostX`  | Ball-and-Stick model (Behrens et al. 2007; Jabdbi et al, MRM 2012)                             | 5D image (xyz, m, n) for m parameters and n MCMC samples (n=1 implies best-fit parameters). Parameters are f<sub>i</sub>, th<sub>i</sub>, ph<sub>i</sub> (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, D, D<sub>std</sub> (for “multiexponential” model)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+
+The JSON sidecar contains the following key/value pairs common for all models:
+
+| **Key name**     | **Description**                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Shells           | OPTIONAL. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, all shells were used.        |
+| Gradients        | OPTIONAL. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used. |
+| ModelDescription | OPTIONAL. Extended information to describe the model.                                                                                |
+| ModelURL         | OPTIONAL. URL to the implementation of the specific model utilized.                                                                  |
+| Parameters       | OPTIONAL. A dictionary of model parameters (see below).                                                                              |
+
+Parameters that may be stored within the JSON sidecar "Parameters" field depend on the particular model used:
+
+-   `DTI` :
+
+    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
+    -   `OutlierRejection`: boolean
+    -   `RESTORESigma` : value
+
+-   `DKI` and `WMTI`:
+
+    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
+
+-   `CSD`:
+
+    -   `Tissue` : string
+    -   `SphericalHarmonicDegree` : value
+    -   `ResponseFunctionZSH` : values (1 row per unique *b*-value as listed in "`Shells`"; 1 column per even harmonic degree starting from zero)
+    -   `ResponseFunctionTensor` : values (vector of 4 values: three tensor eigenvalues, then reference b=0 intensity)
+    -   `SphericalHarmonicBasis` : {`MRtrix3`,`DESCOTEAUX`}
+    -   `NonNegativityConstraint` : {`soft`,`hard`}
+
+-   `NODDI`:
+
+    -   `DPar` : value
+    -   `DIso` : value
+    -   `Lambda1` : value
+    -   `Lambda2` : value
+
+-   `DSI` :
+
+    -   `GridSize` : value
+    -   `RStart` : value
+    -   `RStep` : value
+    -   `REnd` : value
+    -   `FilterWidth` : value
+
+-   `CSA` :
+
+    -   `SphericalHarmonicOrder` : value
+    -   `Smoothing` : value
+    -   `Basis` : value
+
+-   `SHORE` :
+
+    -   `RadialOrder` : value
+    -   `Zeta` : value
+    -   `LambdaN` : value
+    -   `LambdaL` : value
+    -   `Tau` : value
+    -   `ConstrainE0` : value
+    -   `PositiveConstraint` : value
+    -   `PosGrid` : value
+    -   `PosRadius` : value
+
+-   `MAPMRI` :
+
+    -   `RadialOrder` : value
+    -   `LaplacianRegularization` : bool
+    -   `LaplacianWeighting` : value
+    -   `PositivityConstraint` : bool
+    -   `Tau` : value
+    -   `ConstrainE0` : value
+    -   `PositiveConstraint` : value
+    -   `PosGrid` : value
+    -   `PosRadius` : value
+    -   `AnisotropicScaling` : bool
+    -   `EigenvalueThreshold` : value
+    -   `PosGrid` : value
+    -   `BvalThreshold` : value
+    -   `DTIScaleEstimation` : bool
+    -   `StaticDiffusivity` : value
+
+-   `FORECAST` :
+
+    -   `Sphere` : value
+    -   `DecAlg` : value
+    -   `LambdaLb` : value
+    -   `SphericalHarmonicsOrder` : value
+
+-   `fwDTI` :
+
+    -   `FitMethod` : {"WLS","NLLS"}
+
+-   `BEDPOSTX` :
+
+    -   `NFibers` : value
+    -   `Fudge` : value
+    -   `BurnIn` : value
+    -   `NJumps` : value
+    -   `SampleEvery` : value
+    -   `Model` : {`monoexponential`,`multiexponentialStick`,`multiexponentialZeppelin`}
+
+Examples:
+
+A Diffusion Tensor fit:
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
+            sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
+```
+
+Contents of JSON file:
+
+```JSON
+{
+    "Parameters": {
+        "FitMethod": "WLS"
+    }
+}
+```
+
+A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_model-CSD_desc-WM_diffmodel.nii.gz
+            sub-01_model-CSD_desc-WM_diffmodel.json
+            sub-01_model-CSD_desc-GM_diffmodel.nii.gz
+            sub-01_model-CSD_desc-GM_diffmodel.json
+            sub-01_model-CSD_desc-CSF_diffmodel.nii.gz
+            sub-01_model-CSD_desc-CSF_diffmodel.json
+```
+
+Contents of JSON file (using "`_tissue-WM`" as example):
+
+```JSON
+{
+    "Shells": [ 0, 1000, 2000, 3000 ],
+    "Parameters": {
+        "Tissue": "White matter",
+        "SphericalHarmonicDegree": 8,
+        "ResponseFunctionZSH": [ [ 15335 0 0 0 0 0 ],
+                                 [ 7688 -2766 597 -82 10 -5 ],
+                                 [ 5258 -2592 1024 -270 48 -11 ],
+                                 [ 4226 -2193 1124 -436 119 -19 ] ]
+        "SphericalHarmonicBasis": "MRtrix3",
+        "NonNegativityConstraint": "hard"
+    }
+}
+```
+
+A NODDI fit:
+
+```Text
+my_diffusion_pipeline/
+    sub-01/
+        dwi/
+            sub-01_model-NODDI_parameter-ICVF_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-OD_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-ISOVF_diffmodel.nii.gz
+            sub-01_model-NODDI_parameter-direction_diffmodel.nii.gz
+            sub-01_model-NODDI_diffmodel.json
+```
+
+## Model-derived maps (output parameters)
+
+Models output maps of estimated parameters. Commonly one parameter is estimated
+per voxel; we call these maps of parameters. Two types of maps are described in
+this specification: scalar and vector maps. Scalar maps are saved as 3D
+.nii/nii.gz files. Vector maps are saved as 4D .nii/nii.gz files. Below the
+specification for the naming of the files and a the list of currently accepted
+fields for the maps.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<label>]_<parameter>.nii[.gz]
+```
+
+### Scalar maps
+
+These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
+
+| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale                       |
+| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------------------- |
+| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]                    |
+| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
+| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
+| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
+| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
+| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                            |
+| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                            |
+| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                            |
+| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]                  |
+| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
+| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
+| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms <sup>1</sup> |
+| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms              |
+| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]                 |
+| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]                 |
+
+<sup>1</sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2</sup>/ms should be approximately 3.0.
+
+### Directionally-encoded colour (DEC) maps
+
+These maps are saved as 4D NIfTI files with 3 volumes (x,y,z,{RGB}), where the
+three values in each voxel correspond to red, green and blue components indicating
+directionality of the underlying model (each of which must be a non-negative value),
+and the norm of the vector encodes any scalar parameter from the diffusion model.
+Images encoded in this way should include the field "`_desc-DEC`" in order to
+distinguish them from vector-valued maps (see below).
+
+A common example is DEC FA maps, where the fractional anisotropy from the diffusion
+tensor model is coloured according to the direction of the principal eigenvector:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>_model-DTI_desc-DEC_FA.nii[.gz]
+```
+
+### Vector-valued maps
+
+These maps are saved as 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
+encodes both a direction in 3D space and some quantitiative value (these are
+sometimes referred to as "fixels"). The number of volumes in the image must be
+3 times the maximal number of fixels that can appear in any voxel in the image
+(since 3 volumes are required to represent the data for each individual fixel).
+For voxels that contain less than this number of fixels, the excess volumes
+should contain either zero-filling, or NaN values. Exactly what is encoded by
+the amplitude of each XYZ triplet depends on the underlying model properties
+that were used to derive the map, with some examples being:
+
+| `<map_label>` values | Description                                                 |
+| -------------------- | ----------------------------------------------------------- |
+| PDF                  | Diffusion propagator                                        |
+| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI) |
+| PEAKS                | Directions and amplitudes of ODF maxima on the sphere       |
+
+## Describing tractography
+
+Tractography normally generates one of two primary file types: tractograms or
+NIfTi files containing maps. Tractograms are files containing a collection of
+streamlines, which are objects describing the path of idealized brain fiber
+fascicles (ensembles of neural fibers that travel together). Tractography
+visitation maps contain 3D spatial histograms of the number / fraction of
+streamlines intersecting each voxel, but do not contain the individual
+streamlines trajectories themselves. Two tractogram file formats are supported;
+tractography visitation maps should be saved as NIfTIs.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
+```
+
+### Filename keys
+
+`desc` (optional) – A way to refer to a specific instance of the tractography
+process. The combination of tractography methods and parameters that were used
+to create this tractography result should be described in the associated JSON
+file.
+
+`subset` (optional) – A label descriptor for the the subset of streamlines
+included in this file; if not specified, a whole brain tractography is assumed
+(a tractogram). Example of subsets can be `short` if only short streamlines were
+kept, or `subsampled50` if only 50% of the streamlines were kept.
+
+### File formats
+
+-   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
+-   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
+
+### JSON Metadata
+
+We have two main classes of tractography algorithms: Global or Local
+tractography, each with various supported algorithms.
+
+| Class  | Algorithms | Reference                                                                                                                            |
+| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
+| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
+| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
+| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
+| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
+| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
+| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
+| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
+| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
+| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
+
+The JSON sidecar contains the following key/value pairs:
+
+| **Key name**       | **Description**                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
+| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
+| Count              | REQUIRED. integer                                                                                                    |
+| Description        | OPTIONAL. string                                                                                                     |
+| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
+| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
+| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
+
+RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| AnatomicalType    | {`ACT`,`CMC`}                                                                               |
+| AnatomicalImage   | string (name of anatomical tissue segmentation image)                                       |
+| Include           | list of names of inclusion ROIs (streamlines must intersect all)                            |
+| OrderedInclude    | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
+| Exclude           | list of names of exclusion ROIs (streamlines must not intersect any)                        |
+| Mask              | list of names of mask ROIs (streamlines must exist within)                                  |
+
+RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                      |
+| ----------------- | ---------------------------------------------------- |
+| Units             | {`mm`,`norm`} (applies to all within "`Parameters`") |
+| StepSize          | value                                                |
+| AngleCurvature    | value (maximum angle per step)                       |
+| RadiusCurvature   | value (minimal radius of curvature)                  |
+| MinimumLength     | value                                                |
+| MaximumLength     | value                                                |
+| IntegrationOrder  | integer                                              |
+| Unidirectional    | bool                                                 |
+
+RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
+
+| **Key name** | **Description**                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
+| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
+| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
+| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
+| Count        | integer                                                                                                                  |
+
+Example:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            sub-01_desc-DET_tractography.trk
+            sub-01_desc-DET_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "local",
+    "TractographyMethod": "deterministic",
+    "Parameters": {
+        "StepSize": 0.5
+    }
+}
+```
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            sub-01_subset-shortfibers_tractography.trk
+            sub-01_subset-shortfibers_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "global",
+    "TractographyMethod": "UKF",
+    "Description": "UKF tracking where only short fibers were kept."
+    "Parameters": {
+        "MaximumLength": 50.0
+    }
+}
+```

From 86facea38adbee56925d2f7afa31468535133ede Mon Sep 17 00:00:00 2001
From: oesteban <code@oscaresteban.es>
Date: Wed, 18 Sep 2019 10:28:49 -0700
Subject: [PATCH 02/65] MAINT: Split out tractography

This PR splits the tractography section from the diffusion derivatives
document, so that #5 is easier to merge.
The new ``05-diffusion-derivatives-tractography.md`` file will remain
orphaned, but kept there as a base for the time we tackle tractography.
It shouldn't be merged into the derivatives branch until it is ready.
---
 .../05-diffusion-derivatives-tractography.md  | 137 +++++++++++++++++
 .../05-diffusion-derivatives.md               | 138 ------------------
 2 files changed, 137 insertions(+), 138 deletions(-)
 create mode 100644 src/05-derivatives/05-diffusion-derivatives-tractography.md

diff --git a/src/05-derivatives/05-diffusion-derivatives-tractography.md b/src/05-derivatives/05-diffusion-derivatives-tractography.md
new file mode 100644
index 00000000..671be71d
--- /dev/null
+++ b/src/05-derivatives/05-diffusion-derivatives-tractography.md
@@ -0,0 +1,137 @@
+## Describing tractography
+
+Tractography normally generates one of two primary file types: tractograms or
+NIfTi files containing maps. Tractograms are files containing a collection of
+streamlines, which are objects describing the path of idealized brain fiber
+fascicles (ensembles of neural fibers that travel together). Tractography
+visitation maps contain 3D spatial histograms of the number / fraction of
+streamlines intersecting each voxel, but do not contain the individual
+streamlines trajectories themselves. Two tractogram file formats are supported;
+tractography visitation maps should be saved as NIfTIs.
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
+```
+
+### Filename keys
+
+`desc` (optional) – A way to refer to a specific instance of the tractography
+process. The combination of tractography methods and parameters that were used
+to create this tractography result should be described in the associated JSON
+file.
+
+`subset` (optional) – A label descriptor for the the subset of streamlines
+included in this file; if not specified, a whole brain tractography is assumed
+(a tractogram). Example of subsets can be `short` if only short streamlines were
+kept, or `subsampled50` if only 50% of the streamlines were kept.
+
+### File formats
+
+-   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
+-   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
+
+### JSON Metadata
+
+We have two main classes of tractography algorithms: Global or Local
+tractography, each with various supported algorithms.
+
+| Class  | Algorithms | Reference                                                                                                                            |
+| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
+| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
+| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
+| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
+| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
+| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
+| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
+| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
+| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
+| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
+
+The JSON sidecar contains the following key/value pairs:
+
+| **Key name**       | **Description**                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
+| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
+| Count              | REQUIRED. integer                                                                                                    |
+| Description        | OPTIONAL. string                                                                                                     |
+| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
+| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
+| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
+
+RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| AnatomicalType    | {`ACT`,`CMC`}                                                                               |
+| AnatomicalImage   | string (name of anatomical tissue segmentation image)                                       |
+| Include           | list of names of inclusion ROIs (streamlines must intersect all)                            |
+| OrderedInclude    | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
+| Exclude           | list of names of exclusion ROIs (streamlines must not intersect any)                        |
+| Mask              | list of names of mask ROIs (streamlines must exist within)                                  |
+
+RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
+
+| **Key name**      | **Description**                                      |
+| ----------------- | ---------------------------------------------------- |
+| Units             | {`mm`,`norm`} (applies to all within "`Parameters`") |
+| StepSize          | value                                                |
+| AngleCurvature    | value (maximum angle per step)                       |
+| RadiusCurvature   | value (minimal radius of curvature)                  |
+| MinimumLength     | value                                                |
+| MaximumLength     | value                                                |
+| IntegrationOrder  | integer                                              |
+| Unidirectional    | bool                                                 |
+
+RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
+
+| **Key name** | **Description**                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
+| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
+| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
+| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
+| Count        | integer                                                                                                                  |
+
+Example:
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            sub-01_desc-DET_tractography.trk
+            sub-01_desc-DET_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "local",
+    "TractographyMethod": "deterministic",
+    "Parameters": {
+        "StepSize": 0.5
+    }
+}
+```
+
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            sub-01_subset-shortfibers_tractography.trk
+            sub-01_subset-shortfibers_tractography.json
+```
+
+```JSON
+{
+    "TractographyClass": "global",
+    "TractographyMethod": "UKF",
+    "Description": "UKF tracking where only short fibers were kept.",
+    "Parameters": {
+        "MaximumLength": 50.0
+    }
+}
+```
diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 2c08e86e..1c4047a8 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -327,141 +327,3 @@ that were used to derive the map, with some examples being:
 | PDF                  | Diffusion propagator                                        |
 | EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI) |
 | PEAKS                | Directions and amplitudes of ODF maxima on the sphere       |
-
-## Describing tractography
-
-Tractography normally generates one of two primary file types: tractograms or
-NIfTi files containing maps. Tractograms are files containing a collection of
-streamlines, which are objects describing the path of idealized brain fiber
-fascicles (ensembles of neural fibers that travel together). Tractography
-visitation maps contain 3D spatial histograms of the number / fraction of
-streamlines intersecting each voxel, but do not contain the individual
-streamlines trajectories themselves. Two tractogram file formats are supported;
-tractography visitation maps should be saved as NIfTIs.
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
-```
-
-### Filename keys
-
-`desc` (optional) – A way to refer to a specific instance of the tractography
-process. The combination of tractography methods and parameters that were used
-to create this tractography result should be described in the associated JSON
-file.
-
-`subset` (optional) – A label descriptor for the the subset of streamlines
-included in this file; if not specified, a whole brain tractography is assumed
-(a tractogram). Example of subsets can be `short` if only short streamlines were
-kept, or `subsampled50` if only 50% of the streamlines were kept.
-
-### File formats
-
--   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
--   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
-
-### JSON Metadata
-
-We have two main classes of tractography algorithms: Global or Local
-tractography, each with various supported algorithms.
-
-| Class  | Algorithms | Reference                                                                                                                            |
-| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
-| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
-| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
-| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
-| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
-| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
-| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
-| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
-| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
-| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
-
-The JSON sidecar contains the following key/value pairs:
-
-| **Key name**       | **Description**                                                                                                      |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
-| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
-| Count              | REQUIRED. integer                                                                                                    |
-| Description        | OPTIONAL. string                                                                                                     |
-| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
-| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
-| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
-
-RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**      | **Description**                                                                             |
-| ----------------- | ------------------------------------------------------------------------------------------- |
-| AnatomicalType    | {`ACT`,`CMC`}                                                                               |
-| AnatomicalImage   | string (name of anatomical tissue segmentation image)                                       |
-| Include           | list of names of inclusion ROIs (streamlines must intersect all)                            |
-| OrderedInclude    | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
-| Exclude           | list of names of exclusion ROIs (streamlines must not intersect any)                        |
-| Mask              | list of names of mask ROIs (streamlines must exist within)                                  |
-
-RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**      | **Description**                                      |
-| ----------------- | ---------------------------------------------------- |
-| Units             | {`mm`,`norm`} (applies to all within "`Parameters`") |
-| StepSize          | value                                                |
-| AngleCurvature    | value (maximum angle per step)                       |
-| RadiusCurvature   | value (minimal radius of curvature)                  |
-| MinimumLength     | value                                                |
-| MaximumLength     | value                                                |
-| IntegrationOrder  | integer                                              |
-| Unidirectional    | bool                                                 |
-
-RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
-
-| **Key name** | **Description**                                                                                                          |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
-| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
-| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
-| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
-| Count        | integer                                                                                                                  |
-
-Example:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_desc-DET_tractography.trk
-            sub-01_desc-DET_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "local",
-    "TractographyMethod": "deterministic",
-    "Parameters": {
-        "StepSize": 0.5
-    }
-}
-```
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_subset-shortfibers_tractography.trk
-            sub-01_subset-shortfibers_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "global",
-    "TractographyMethod": "UKF",
-    "Description": "UKF tracking where only short fibers were kept."
-    "Parameters": {
-        "MaximumLength": 50.0
-    }
-}
-```

From 5ab7dc325d4c61ccb1e1e3e425b3b614bc274b1e Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 4 Jul 2019 21:20:31 +1000
Subject: [PATCH 03/65] First commit for restructuring of DWI derivatives

---
 .../05-diffusion-derivatives.md               | 814 +++++++++++++-----
 1 file changed, 582 insertions(+), 232 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 1c4047a8..10b9b4ae 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -1,9 +1,9 @@
 # Diffusion derivatives
 
-## Preprocessed diffusion weighted images
+## Preprocessed diffusion-weighted images
 
 Multiple different versions of preprocessing can be stored for the same source
-data. To distinguish them from each other, the `desc` filename keyword can be
+data. To distinguish them from each other, the `desc` fileneame keyword can be
 used. Details of preprocessing performed for each variation of the processing
 should be included in the pipeline documentation.
 
@@ -18,106 +18,339 @@ should be included in the pipeline documentation.
 ```
 
 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
+see [Common Data Types](02-common-data-types.md)), and MAY additionally be used to
 store information about what preprocessing options were used (for example
 whether denoising was performed, corrections applied for field inhomogeneity /
-gradient non-linearity / subject motion / eddy currents, intensity normalization was
-performed, etc.).
+gradient non-linearity / subject motion / eddy currents, etc.).
 
 Additional reserved JSON metadata fields:
 
-| **Key name**                   | **Description**                                                                                                              |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| Denoising                      | OPTIONAL. String. Denoising method                                                                                           |
-| MotionCorrection               | OPTIONAL. Boolean. Motion correction                                                                                         |
-| EddyCurrentCorrection          | OPTIONAL. Boolean. Eddy currents corrections                                                                                 |
-| IntensityNormalizationMethod   | OPTIONAL. String. Method (if any) used for intensity normalization                                                           |
-| FieldInhomogeneityCorrection   | OPTIONAL. Boolean. Correction for geometric distortions arising from magnetic field inhomogeneity                            |
-| GradientNonLinearityCorrection | OPTIONAL. String. Correction for non-linear gradients; allowed values: `none`, `geometry`, `gradients`, `geometry&gradients` |
+| **Key name**                           | **Description**                                                                                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Denoising                              | OPTIONAL. String. Denoising method                                                                                                                |
+| GibbsRingingCorrection                 | OPTIONAL. Boolean. Removal of Gibbs ringing artifacts                                                                                             |
+| MotionCorrection                       | OPTIONAL. String. Motion correction; allowed values: `none`, `volume`, `slice`                                                                    |
+| EddyCurrentCorrection                  | OPTIONAL. String. Eddy current distortion correction; reserved values: `none`, `linear`, `quadratic`, `cubic`                                     |
+| IntensityNormalizationMethod           | OPTIONAL. String. Method (if any) used for intensity normalization                                                                                |
+| FieldInhomogeneityEstimation           | OPTIONAL. String. Method (if any) used for estimation of the B0 inhomogeneity field; reserved values: `multiecho`, `phaseencode`, `registration`  |
+| FieldInhomogeneityCorrection           | OPTIONAL. String. Correction for geometric distortions arising from B0 magnetic field inhomogeneity; reserved values: `none`, `static`, `dynamic` |
+| GradientNonLinearityGeometryCorrection | OPTIONAL. Boolean. Correction for geometric distortions arising from non-linearity of gradients                                                   |
+| GradientNonLinearityQSpaceCorrection   | OPTIONAL. Boolean. Correction for spatial inhomogeneity of diffusion sensitisation gradient strength                                              |
+| SliceDropoutDetection                  | OPTIONAL. Boolean. Detection of signal dropout in acquired slices during pre-processing                                                           |
+| SliceDropoutReplacement                | OPTIONAL. Boolean. Replacement of image data within slices containing signal dropout with predicted values                                        |
+| BiasFieldCorrectionMethod              | OPTIONAL. String. Method (if any) used for correction of B1 RF field inhomogeneity                                                                |
 
-## Diffusion Models (and input parameters)
+## Diffusion models
 
-Diffusion MRI can be modeled using various paradigms to extract a more easily
-understandable representation of the diffusion process and the underlying
-structure. To do so, parameters might be needed to control how the signal is fit
-to the model. Those parameters are called **input parameters** in the following.
-Once the model is fit, the resulting representation can be saved using a number
-of values per voxel. Those values will be called **output** or **estimated
-parameters** in the following.
+Diffusion MRI can be modeled using various paradigms to extract more
+informative representations of the diffusion process and the underlying
+biological structure. A wide range of such models are available, each of
+which has its own unique requirements with respect to:
 
-**Estimated parameters** are saved as NIFTI files (see section Models for the
-expected content of each model), and **input parameters** are saved in the
-sidecar JSON file.
+-   The input parameters required to define / constrain the model;
 
-The following is a general example of naming convention:
+-   The appropriate data representation in which the resulting
+    parameters estimated of / from the model are stored on the filesystem;
+
+-   The requirements for encapsulation and complete representation of
+    derived orientation information, which is a key strength of diffusion
+    MRI but presents unique challenges for correct interpretation.
+
+### Parameter terminology
+
+1.  *Intrinsic* parameter: Item that is the direct result of fitting
+    the diffusion model to the empirical diffusion-weighted data.
+
+1.  *Input* parameter: Item that influences the conformation of the
+    diffusion model to the empirical diffusion-weighted data.
+
+1.  *Extrinsic* parameter: Item that can be calculated from prior
+    estimated intrinsic model parameters, without necessitating reference
+    to the empirical diffusion-weighted data.
+
+### File names
 
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam1>_<model>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam2>_<model>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.json]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
 ```
 
-The following models are codified and should be used in the `model-<label>`
-field. If a new model is used, common sense should be used to derive a name
-following the BIDS standard, and should ideally be integrated in a follow-up
-version of the specification.
+-   File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
+    provides basic model information and [input model parameters].
 
-| 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)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+-   OPTIONAL file "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+    provides only information or parameters relevant to derivation of the
+    relevant [extrinsic model parameter] based on prior estimates of
+    [intrinsic model parameters].
 
-The JSON sidecar contains the following key/value pairs common for all models:
+-   If all [intrinsic model parameters] are contained within a single image
+    file, field "`_parameter-*`" MUST be omitted (for intrinsic parameter
+    image only):
 
-| **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).                                                                              |
+    ```Text
+    <pipeline_name>/
+        sub-<participant_label>/
+            dwi/
+                <source_keywords>[_space-<space>][_desc-<label>]_<model>.nii[.gz]
+                <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+    ```
 
-Parameters that may be stored within the JSON sidecar "Parameters" field depend on the particular model used:
+### Data representations
 
--   `DTI` :
+1.  Scalars
 
-    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
-    -   `OutlierRejection`: boolean
-    -   `RESTORESigma` : value
+    Any model parameter image (whether intrinsic or extrinsic) where a
+    solitary value is defined in each 3D image voxel is referred to here as a
+    "scalar" image.
 
--   `DKI` and `WMTI`:
+1.  Directionally-Encoded Colours (DEC)
 
-    -   `FitMethod` : {`WLS`,`IWLS`,`OLS`,`NLLS`}
+    4D image with three volumes, intended to be interpreted as red, green
+    and blue colour intensities for visualisation
+    \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
+    values.
 
--   `CSD`:
+1.  Spherical coordinates
 
-    -   `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`}
+    4D image where data across volumes within each voxel encode one or
+    more discrete orientations using polar angles, optionally exploiting
+    the distance from origin to encode the value of some parameter.
 
--   `NODDI`:
+    1. Value per direction
 
-    -   `DPar` : value
-    -   `DIso` : value
-    -   `Lambda1` : value
-    -   `Lambda2` : value
+        Each consecutive triplet of image volumes encodes a spherical
+        coordinate, using ISO convention for both the order of parameters
+        and reference frame for angles:
+
+        1.  Distance from origin; value of embedded parameter SHOULD be
+            indicated in "`_parameter-*`" filename field;
+
+        1.  Inclination / polar angle, in radians, relative to the zenith
+            direction being the positive direction of the *third* reference
+            axis (see [orientation specification]);
+
+        1.  Azimuth angle, in radians, orthogonal to the zenith direction,
+            with value of 0.0 corresponding to the *first* reference axis
+            (see [orientation specification]), increasing according to the
+            right-hand rule about the zenith direction.
+
+        Number of image volumes is equal to (3x*N*), where *N* is the maximum
+        number of discrete orientations in any voxel in the image.
+
+    1.  Directions only
+
+        Each consecutive pair of image volumes encodes inclination /
+        azimuth pairs, with order & convention identical to that above
+        (equivalent to spherical coordinate with assumed unity distance from
+        origin).
+
+        Number of image volumes is equal to (2x*N*), where *N* is the maximum
+        number of discrete orientations in any voxel in the image.
+
+1.  3-Vectors
+
+    4D image where data across volumes within each voxel encode one or
+    more discrete orientations using triplets of axis dot products.
+
+    If not all 3-vectors are of unit norm, parameter encoded as vector
+    norm SHOULD be indicated in "`_parameter-*`" filename field.
+
+    Number of image volumes is equal to (3x*N*), where *N* is the maximum
+    number of discrete orientations in any voxel in the image.
+
+1.  Spherical Harmonics (SH)
+
+    4D image where data across volumes within each voxel represent a
+    continuous function spanning the 2-sphere as coefficient values using a
+    spherical harmonic basis.
+
+    Number of image volumes depends on the spherical harmonic basis employed,
+    and the maximal spherical harmonic degree *l<sub>max</sub>*.
+
+1.  Amplitudes
+
+    4D image where data across volumes within each voxel represent
+    amplitudes of a discrete function spanning the 2-sphere.
+
+    Number of image volumes corresponds to the number of discrete directions
+    on the unit sphere along which samples for the function in each voxel
+    are provided.
+
+1.  Probability Distribution Functions (PDF)
+
+1.  Parameter vectors
+
+    4D image containing, for every image voxel, data corresponding to some
+    set of model parameters, the names and order of which are defined within
+    the [intrinsic model parameters] section.
+
+### Orientation specification
+
+| **Key name**                | **Relevant [data representations]**                                                                                                  | **Description**                                                                                                                                                                                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AntipodalSymmetry`         | [Spherical coordinates], [3-vectors], [spherical harmonics], [amplitudes], [probability distribution functions], [parameter vectors] | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
+| `Directions`                | [Amplitudes]                                                                                                                         | REQUIRED. List. Data are either [spherical coordinates] ([directions only]) or [3-vectors] with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                                              |
+| `FillValue`                 | [Spherical coordinates], [3-vectors]                                                                                                 | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
+| `OrientationRepresentation` | All except [scalar]                                                                                                                  | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation] used to encode orientation information.                                                                             |
+| `ReferenceAxes`             | All except [scalar]                                                                                                                  | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
+| `SphericalHarmonicBasis`    | [Spherical harmonics (SH)]                                                                                                           | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonic coefficients.                                                                                            |
+| `SphericalHarmonicDegree`   | [Spherical harmonics (SH)]                                                                                                           | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
+
+#### Spherical Harmonics (SH) bases
 
--   `DSI` :
+-   `MRtrix3`
+
+    -   Antipodally symmetric: all basis functions with odd degree are
+        assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
+
+    -   Functions assumed to be real: conjugate symmetry is assumed, i.e.
+        *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
+        conjugate.
+
+    -   Mapping of image volumes to spherical harmonic basis function
+        coefficients:
+
+        | **Volume** | **Coefficient**                   |
+        | ---------- | --------------------------------- |
+        | 0          | *l* = 0, *m* = 0                  |
+        | 1          | *l* = 2, *m* = 2 (imaginary part) |
+        | 2          | *l* = 2, *m* = 1 (imaginary part) |
+        | 3          | *l* = 2, *m* = 0                  |
+        | 4          | *l* = 2, *m* = 1 (real part)      |
+        | 5          | *l* = 2, *m* = 2 (real part)      |
+        | 6          | *l* = 4, *m* = 4 (imaginary part) |
+        | 7          | *l* = 4, *m* = 3 (imaginary part) |
+        | ...        | etc.                              |
+
+    -   Normalisation: ***TODO***
+
+    Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+    and number of image volumes *N*:
+
+        *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+
+        | ***l<sub>max</sub>*** | ***N*** |
+        | --------------------- | ------- |
+        | 0                     | 1       |
+        | 2                     | 6       |
+        | 4                     | 15      |
+        | 6                     | 28      |
+        | 8                     | 45      |
+        | ...                   | etc.    |
+
+    Relationship between maximal degree of *zonal* spherical harmonic
+    function (spherical harmonics function where all *m* != 0 terms are
+    assumed to be zero; used for e.g. response function definition) and
+    number of coefficients *N*:
+
+        *N* = 1 + (*l<sub>max</sub>* / 2)
+
+        | ***l<sub>max</sub>*** | ***N*** |
+        | --------------------- | ------- |
+        | 0                     | 1       |
+        | 2                     | 2       |
+        | 4                     | 3       |
+        | 6                     | 4       |
+        | 8                     | 5       |
+        | ...                   | etc.    |
+
+ -   `Descoteaux`
+
+### Intrinsic model parameters
+
+The following models are codified within the specification, and the model
+label should be used as the final field in the filename for storage of any
+intrinsic or extrinsic parameters. 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 future version of the specification.
+
+| Model label | Full Name                                                                                                                                       | [Data representation]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates] image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics (SH)] image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors] image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                           |
+| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions (PDF)]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors] image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar] image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors] 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One scalar image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three scalar images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors] image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes] image<br>OR<br>Single [spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors] image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One scalar image with parameter name "`awf`", representing the estimated axonal water fraction |
+
+The JSON sidecar for the intrinsic diffusion model parameters may contain
+the following key/value pairs irrespective of the particular model:
+
+| **Key name**     | **Description**                                                                                                                                                                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gradients        | OPTIONAL. List of 3-vectors. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used.                                      |
+| Shells           | OPTIONAL. List of floats. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, it should be assumed that all shells were used during model fitting. |
+| Mask             | OPTIONAL. String. Name of image that was used as a binary mask to specify those voxels for which the model was fit.                                                                          |
+| ModelDescription | OPTIONAL. String. Extended information to describe the model.                                                                                                                                |
+| ModelURL         | OPTIONAL. String. URL to the implementation of the specific model utilized.                                                                                                                  |
+| Parameters       | OPTIONAL. Dictionary. *Input* model parameters that are constant across the image (see below).                                                                                               |
+
+#### Model bootstrapping
+
+Results of model bootstrapping can be provided by concatenating multiple
+realisations of model intrinsic parameters along an additional image axis.
+
+The corresponding sidecar JSON file may include dictionary field
+"`BootstrapParameters`", descibing those input parameters specific to
+the determination and export of multiple realisations of the model fit
+in each image voxel.
+
+### Input model parameters
+
+Parameters that may / must be stored within the JSON sidecar "`Parameters`"
+field depends on the particular model used.
+
+"`Parameters`" fields that may be applicable to multiple models:
+
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FitMethod        | OPTIONAL. String. The optimisation procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Options are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
+| Iterations       | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                    |
+| OutlierRejection | OPTIONAL. Boolean. Value indicating whether or not rejection of outlier values was performed during fitting of the intrinsic model parameters.                                                                                                                                                         |
+| Samples          | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters are provided.                                                                                                                                  |
+
+Reserved keywords for models built into the specification are as follows:
+
+-   `bs` :
+
+    -   `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
+    -   `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
+    -   `ModelBall`: String. Model used to describe the "ball" component in the model.
+    -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
+
+-   `csa` :
+
+    -   `SphericalHarmonicOrder` : value
+    -   `Smoothing` : value
+    -   `Basis` : value
+
+-   `csd`:
+
+    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
+    -   `ResponseFunctionZSH`: Two options:
+        -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
+        -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
+    -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
+    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics (SH) bases] section.
+    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics].
+    -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
+
+-   `dsi` :
 
     -   `GridSize` : value
     -   `RStart` : value
@@ -125,25 +358,18 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
     -   `REnd` : value
     -   `FilterWidth` : value
 
--   `CSA` :
+-   `dti` :
 
-    -   `SphericalHarmonicOrder` : value
-    -   `Smoothing` : value
-    -   `Basis` : value
+    -   `RESTORESigma`: Float
 
--   `SHORE` :
+-   `forecast` :
 
-    -   `RadialOrder` : value
-    -   `Zeta` : value
-    -   `LambdaN` : value
-    -   `LambdaL` : value
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
+    -   `Sphere` : value
+    -   `DecAlg` : value
+    -   `LambdaLb` : value
+    -   `SphericalHarmonicsOrder` : value
 
--   `MAPMRI` :
+-   `mapmri` :
 
     -   `RadialOrder` : value
     -   `LaplacianRegularization` : bool
@@ -161,169 +387,293 @@ Parameters that may be stored within the JSON sidecar "Parameters" field depend
     -   `DTIScaleEstimation` : bool
     -   `StaticDiffusivity` : value
 
--   `FORECAST` :
+-   `noddi`:
 
-    -   `Sphere` : value
-    -   `DecAlg` : value
-    -   `LambdaLb` : value
-    -   `SphericalHarmonicsOrder` : value
+    -   `DPar` : value
+    -   `DIso` : value
+    -   `Lambda1` : value
+    -   `Lambda2` : value
 
--   `fwDTI` :
+-   `shore` :
 
-    -   `FitMethod` : {"WLS","NLLS"}
+    -   `RadialOrder` : value
+    -   `Zeta` : value
+    -   `LambdaN` : value
+    -   `LambdaL` : value
+    -   `Tau` : value
+    -   `ConstrainE0` : value
+    -   `PositiveConstraint` : value
+    -   `PosGrid` : value
+    -   `PosRadius` : value
 
--   `BEDPOSTX` :
+### Extrinsic model parameters
+
+| `<parameter>` value | Description                                                            | [Data representation] | Possible Model sources                          | Unit or scale                                                  |
+| ------------------- | ---------------------------------------------------------------------- | --------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
+| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `ak`                | Axial kurtosis                                                         | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
+| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | Scalar                | { `csd` }                                       | Unitless                                                       |
+| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
+| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
+| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
+| `evec`              | Eigenvector(s)                                                         | [3-vectors]           | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
+| `fsum`              | Sum of partial volume fractions of stick components                    | Scalar                | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
+| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | Scalar                | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
+| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `mk`                | Mean kurtosis                                                          | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
+| `mode`              | Mode of the tensor                                                     | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
+| `msd`               | Mean-Squared Displacement                    | Scalar                | { `mapmri`, `shore` }                           |                                                      |
+| `pdf`               | Diffusion propagator                                                   | [3-vectors]           |                                       |                                                      |
+| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors]           | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
+| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `rk`                | Radial kurtosis                                                        | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
+| `rtap`              | Return To Axis Probability                                             | Scalar                | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `rtop`              | Return To Origin Probability                 | Scalar                | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
+| `rtpp`              | Return To Plane Probability                                            | Scalar                | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `tort`              | Tortuosity of extra-cellular space                   | Scalar                | { `dki` }                                       |                                                      |
+
+While not explicitly included in the table above, *any* scalar extrinsic
+parameter can theoretically be combined with a separate source of orientation
+information from the diffusion model in order to produce a
+[directionally-encoded colours (DEC)], [spherical coordinates] or
+[3-vectors] image.
+
+## Demonstrative examples
+
+-   A basic Diffusion Tensor fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_dti.nii.gz
+                sub-01_dti.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors])
+
+    Contents of JSON file:
+
+    ```JSON
+    {
+        "Model": "Diffusion Tensor",
+        "OrientationRepresentation": "param",
+        "ReferenceAxes": "xyz",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejection": False
+        }
+    }
+    ```
+
+-   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_desc-wm_csd.nii.gz
+                sub-01_desc-wm_csd.json
+                sub-01_desc-gm_csd.nii.gz
+                sub-01_desc-gm_csd.json
+                sub-01_desc-csf_csd.nii.gz
+                sub-01_desc-csf_csd.json
+                sub-01_csd.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics (SH)])
+    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics (SH)])
+    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics (SH)])
+
+    Contents of file "`sub-01_csd.json`" (common to all intrinsic model parameter images):
+
+    ```JSON
+    {
+        "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+        "Shells": [ 0, 1000, 2000, 3000 ],
+        "Parameters": {
+            "SphericalHarmonicBasis": "MRtrix3",
+            "NonNegativityConstraint": "hard"
+        }
+    }
+    ```
+
+    Contents of JSON file "`sub-01_desc-wm_csd.json`":
+
+    ```JSON
+    {
+        "OrientationRepresentation": "sh",
+        "ReferenceAxes": "xyz",
+        "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
+                                 [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
+                                 [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
+                                 [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
+        "SphericalHarmonicDegree": 8,
+        "Tissue": "White matter"
+    }
+    ```
+
+    Contents of JSON file "`sub-01_desc-gm_csd.json`":
+
+    ```JSON
+    {
+        "OrientationRepresentation": "sh",
+        "ReferenceAxes": "xyz",
+        "ResponseFunctionZSH": [ [ 1041.0 ],
+                                 [ 436.6 ],
+                                 [ 224.9 ],
+                                 [ 128.8 ] ],
+        "SphericalHarmonicDegree": 0,
+        "Tissue": "Grey matter"
+    }
+    ```
+
+-   A NODDI fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_parameter-icvf_noddi.nii.gz
+                sub-01_parameter-isovf_noddi.nii.gz
+                sub-01_parameter-od_noddi.nii.gz
+                sub-01_parameter-direction_noddi.nii.gz
+                sub-01_parameter-direction_noddi.json
+                sub-01_noddi.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors])
+
+    Contents of file "`sub-01_noddi.json`" (common to all intrinsic model parameter images):
+
+    ```JSON
+    {
+        "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+        "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
+    }
+    ```
 
-    -   `NFibers` : value
-    -   `Fudge` : value
-    -   `BurnIn` : value
-    -   `NJumps` : value
-    -   `SampleEvery` : value
-    -   `Model` : {`monoexponential`,`multiexponentialStick`,`multiexponentialZeppelin`}
+    Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
 
-Examples:
+    ***TODO Don't know what reference axes are used by default for NODDI***
 
-A Diffusion Tensor fit:
+    ```JSON
+    {
+        "OrientationRepresentation": "3vector",
+        "ReferenceAxes": "???"
+    }
+    ```
+
+-   An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
+    bootstrap realisations):
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_desc-mean_parameter-bzero_bs.nii.gz
+                sub-01_desc-mean_parameter-dmean_bs.nii.gz
+                sub-01_desc-mean_parameter-dstd_bs.nii.gz
+                sub-01_desc-mean_parameter-sticks_bs.nii.gz
+                sub-01_desc-mean_parameter-sticks_bs.json
+                sub-01_desc-merged_parameter-sticks_bs.nii.gz
+                sub-01_desc-merged_parameter-sticks_bs.json
+                sub-01_bs.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar])
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates], distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates], distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+
+    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
+    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
+    files are identical):
+
+    ```JSON
+    {
+        "OrientationRepresentation": "spherical",
+        "ReferenceAxes": "ijk"
+    }
+    ```
+
+    Contents of JSON file "`sub-01_bs.json`":
+
+    ```JSON
+    {
+        "Model": "Ball-And-Sticks model using FSL bedpostx",
+        "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3,
+            "Samples": 50
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    }
+    ```
 
-```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:
+<a name="diffusivity"><sup>1</sup></a>: For example, for free water in body
+temperature, the diffusivity in units of \mu m<sup>2</sup>.ms<sup>-1</sup>
+should be approximately 3.0.
 
-```JSON
-{
-    "Parameters": {
-        "FitMethod": "WLS"
-    }
-}
-```
+-----
 
-A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+<a name="aganj2010">\[Aganj2010\]</a>: Aganj et al. 2010
 
-```Text
-my_diffusion_pipeline/
-    sub-01/
-        dwi/
-            sub-01_model-CSD_desc-WM_diffmodel.nii.gz
-            sub-01_model-CSD_desc-WM_diffmodel.json
-            sub-01_model-CSD_desc-GM_diffmodel.nii.gz
-            sub-01_model-CSD_desc-GM_diffmodel.json
-            sub-01_model-CSD_desc-CSF_diffmodel.nii.gz
-            sub-01_model-CSD_desc-CSF_diffmodel.json
-```
+<a name="basser1994">\[Basser1994\]</a>: Basser et al. 1994
 
-Contents of JSON file (using "`_tissue-WM`" as example):
+<a name="basser1996">\[Basser1996\]</a>: Basser et al. 1996
 
-```JSON
-{
-    "Shells": [ 0, 1000, 2000, 3000 ],
-    "Parameters": {
-        "Tissue": "White matter",
-        "SphericalHarmonicDegree": 8,
-        "ResponseFunctionZSH": [ [ 15335 0 0 0 0 0 ],
-                                 [ 7688 -2766 597 -82 10 -5 ],
-                                 [ 5258 -2592 1024 -270 48 -11 ],
-                                 [ 4226 -2193 1124 -436 119 -19 ] ]
-        "SphericalHarmonicBasis": "MRtrix3",
-        "NonNegativityConstraint": "hard"
-    }
-}
-```
+<a name="behrens2003">\[Behrens2003\]</a> Behrens et al. 2003
 
-A NODDI fit:
+<a name="behrens2007">\[Behrens2007\]</a> Behrens et al. 2007
 
-```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
-```
+<a name="calamante2015">\[Calamante2015\]</a>: Calamante et al. 2015
 
-## Model-derived maps (output parameters)
+<a name="daducci2015">\[Daducci2015\]</a>: Daducci et al. 2015
 
-Models output maps of estimated parameters. Commonly one parameter is estimated
-per voxel; we call these maps of parameters. Two types of maps are described in
-this specification: scalar and vector maps. Scalar maps are saved as 3D
-.nii/nii.gz files. Vector maps are saved as 4D .nii/nii.gz files. Below the
-specification for the naming of the files and a the list of currently accepted
-fields for the maps.
+<a name="descoteaux2009">\[Descoteaux2009\]</a>: Descoteaux et al. 2009
 
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<label>]_<parameter>.nii[.gz]
-```
+<a name="fieremans2011">\[Fieremans2011\]</a>: Fieremans et al. 2011
 
-### Scalar maps
-
-These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
-
-| `<parameter>` value | Description                                                        | Possible Model sources                                                             | Unit or scale                       |
-| ------------------- | ------------------------------------------------------------------ | -----------------------------------------------------------------------------------| ----------------------------------- |
-| FA                  | Fractional Anisotropy                                              | DTI, DKI, WMTI (D, Dh, Dr)                                                         | Unitless \[0-1\]                    |
-| MD                  | Mean diffusivity (also called apparent diffusion coefficient, ADC) | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| AD                  | Axial Diffusivity (also called parallel diffusivity)               | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| RD                  | Radial Diffusivity (also called perpendicular diffusivity)         | DTI, DKI, WMTI (D, Dh, Dr)                                                         | microns<sup>2</sup>/ms <sup>1</sup> |
-| MODE                | Mode of the tensor                                                 | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| LINEARITY           | Tensor linearity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| PLANARITY           | Tensor planarity (Westin 1997)                                     | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| SPHERICITY          | Tensor sphericity (Westin 1997)                                    | DTI, DKI, WMTI (D, Dh, Dr)                                                         |                                     |
-| MK                  | Mean kurtosis                                                      | DKI, WMTI                                                                          | Unitless                            |
-| RK                  | Radial kurtosis                                                    | DKI, WMTI                                                                          | Unitless                            |
-| AK                  | Axial kurtosis                                                     | DKI, WMTI                                                                          | Unitless                            |
-| GFA                 | Generalized Fractional Anisotropy                                  | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\]                  |
-| FSUM                | Sum of partial volume fractions of stick components                | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
-| Fi                  | Volume fraction of stick i                                         | Ball-and-stick(s)                                                                  | Volume fraction \[0-1\]             |
-| D                   | Diffusivity                                                        | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms <sup>1</sup> |
-| DSTD                | Standard deviation of diffusivity                                  | Ball-and-stick(s)                                                                  | microns<sup>2</sup>/ms              |
-| RTPP                | Return to the plane probability                                    | MAPMRI                                                                             | Probability \[0-1\]                 |
-| RTAP                | Return to axis probability                                         | MAPMRI                                                                             | Probability \[0-1\]                 |
-
-<sup>1</sup> For example, for free water in body temperature, the diffusivity in units of microns<sup>2</sup>/ms should be approximately 3.0.
-
-### Directionally-encoded colour (DEC) maps
-
-These maps are saved as 4D NIfTI files with 3 volumes (x,y,z,{RGB}), where the
-three values in each voxel correspond to red, green and blue components indicating
-directionality of the underlying model (each of which must be a non-negative value),
-and the norm of the vector encodes any scalar parameter from the diffusion model.
-Images encoded in this way should include the field "`_desc-DEC`" in order to
-distinguish them from vector-valued maps (see below).
-
-A common example is DEC FA maps, where the fractional anisotropy from the diffusion
-tensor model is coloured according to the direction of the principal eigenvector:
+<a name="hess2006">\[Hess2006\]</a>: Hess et al. 2006
 
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>_model-DTI_desc-DEC_FA.nii[.gz]
-```
+<a name="hoy2014">\[Hoy2014\]</a>: Hoy et al. 2014
+
+<a name="jbabdi2012">\[Jbabdi2012\]</a> Jbabdi et al. 2012
+
+<a name="jensen2005">\[Jensen2005\]</a>: Jensen et al. 2005
+
+<a name="jeurissen2014">\[Jeurissen2014\]</a>: Jeurissen et al. 2014
+
+<a name="ozarslan2008">\[Ozarslan2008\]</a>: Ozarslan et al. 2008
+
+<a name="ozarslan2013">\[Ozarslan2013\]</a>: Ozarslan 2013
+
+<a name="paquette2017">\[Paquette2017\]</a>: Paquette et al 2017
+
+<a name="pajevic1999">\[Pajevic1999\]</a>: Pajevic et al 1999
+
+<a name="tournier2007">\[Tournier2007\]</a>: Tournier et al. 2007
+
+<a name="tuch2004">\[Tuch2004\]</a>: Tuch 1994
+
+<a name="wedeen2008">\[Wedeen2008\]</a>: Wedeen et al. 2008
+
+<a name="westin1997">\[Westin1997\]</a>: Westin 1997
+
+<a name="zhang2012">\[Zhang2012\]</a>: Zhang et al. 2012
 
-### Vector-valued maps
-
-These maps are saved as 4D NIfTI files (x,y,z, 3\*n), where each triplet of volumes
-encodes both a direction in 3D space and some quantitiative value (these are
-sometimes referred to as "fixels"). The number of volumes in the image must be
-3 times the maximal number of fixels that can appear in any voxel in the image
-(since 3 volumes are required to represent the data for each individual fixel).
-For voxels that contain less than this number of fixels, the excess volumes
-should contain either zero-filling, or NaN values. Exactly what is encoded by
-the amplitude of each XYZ triplet depends on the underlying model properties
-that were used to derive the map, with some examples being:
-
-| `<map_label>` values | Description                                                 |
-| -------------------- | ----------------------------------------------------------- |
-| PDF                  | Diffusion propagator                                        |
-| EVECS                | Eigenvectors of a model that has eigenvectors (such as DTI) |
-| PEAKS                | Directions and amplitudes of ODF maxima on the sphere       |
+<a name="zuchelli2017">\[Zuchelli2017\]</a>: Zuchelli et al. 2017

From 1beda57186f7d61c8c7c17f46e80c8a9657f2923 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 16 Jul 2019 18:50:12 +1000
Subject: [PATCH 04/65] BEP016: Small fixes, and try to get links to headers
 working

---
 .../05-diffusion-derivatives.md               | 180 +++++++++---------
 1 file changed, 91 insertions(+), 89 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 10b9b4ae..c82c30a2 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -3,7 +3,7 @@
 ## Preprocessed diffusion-weighted images
 
 Multiple different versions of preprocessing can be stored for the same source
-data. To distinguish them from each other, the `desc` fileneame keyword can be
+data. To distinguish them from each other, the `desc` filename keyword can be
 used. Details of preprocessing performed for each variation of the processing
 should be included in the pipeline documentation.
 
@@ -84,16 +84,16 @@ which has its own unique requirements with respect to:
 ```
 
 -   File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-    provides basic model information and [input model parameters].
+    provides basic model information and [input model parameters](#input-model-parameters).
 
 -   OPTIONAL file "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
     provides only information or parameters relevant to derivation of the
-    relevant [extrinsic model parameter] based on prior estimates of
-    [intrinsic model parameters].
+    relevant [extrinsic model parameter](#extrinsic-model-parameters) based
+    on prior estimates of [intrinsic model parameters](#intrinsic-model-parameters).
 
--   If all [intrinsic model parameters] are contained within a single image
-    file, field "`_parameter-*`" MUST be omitted (for intrinsic parameter
-    image only):
+-   If all [intrinsic model parameters](#intrinsic-model-parameters) are
+    contained within a single image file, field "`_parameter-*`" MUST be
+    omitted (for intrinsic parameter image only):
 
     ```Text
     <pipeline_name>/
@@ -111,12 +111,12 @@ which has its own unique requirements with respect to:
     solitary value is defined in each 3D image voxel is referred to here as a
     "scalar" image.
 
-1.  Directionally-Encoded Colours (DEC)
+1.  Directionally-Encoded Colours
 
     4D image with three volumes, intended to be interpreted as red, green
     and blue colour intensities for visualisation
     \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
-    values.
+    values. Abbreviation "DEC" is regularly used to refer to such data.
 
 1.  Spherical coordinates
 
@@ -135,12 +135,13 @@ which has its own unique requirements with respect to:
 
         1.  Inclination / polar angle, in radians, relative to the zenith
             direction being the positive direction of the *third* reference
-            axis (see [orientation specification]);
+            axis (see [orientation specification](#orientation-specification));
 
         1.  Azimuth angle, in radians, orthogonal to the zenith direction,
             with value of 0.0 corresponding to the *first* reference axis
-            (see [orientation specification]), increasing according to the
-            right-hand rule about the zenith direction.
+            (see [orientation specification](#orientation-specification)),
+            increasing according to the right-hand rule about the zenith
+            direction.
 
         Number of image volumes is equal to (3x*N*), where *N* is the maximum
         number of discrete orientations in any voxel in the image.
@@ -166,11 +167,11 @@ which has its own unique requirements with respect to:
     Number of image volumes is equal to (3x*N*), where *N* is the maximum
     number of discrete orientations in any voxel in the image.
 
-1.  Spherical Harmonics (SH)
+1.  Spherical Harmonics
 
     4D image where data across volumes within each voxel represent a
     continuous function spanning the 2-sphere as coefficient values using a
-    spherical harmonic basis.
+    spherical harmonic (SH) basis.
 
     Number of image volumes depends on the spherical harmonic basis employed,
     and the maximal spherical harmonic degree *l<sub>max</sub>*.
@@ -184,27 +185,27 @@ which has its own unique requirements with respect to:
     on the unit sphere along which samples for the function in each voxel
     are provided.
 
-1.  Probability Distribution Functions (PDF)
+1.  Probability Distribution Functions
 
 1.  Parameter vectors
 
     4D image containing, for every image voxel, data corresponding to some
     set of model parameters, the names and order of which are defined within
-    the [intrinsic model parameters] section.
+    the [intrinsic model parameters](#intrinsic-model-parameters) section.
 
 ### Orientation specification
 
-| **Key name**                | **Relevant [data representations]**                                                                                                  | **Description**                                                                                                                                                                                                                                                          |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `AntipodalSymmetry`         | [Spherical coordinates], [3-vectors], [spherical harmonics], [amplitudes], [probability distribution functions], [parameter vectors] | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
-| `Directions`                | [Amplitudes]                                                                                                                         | REQUIRED. List. Data are either [spherical coordinates] ([directions only]) or [3-vectors] with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                                              |
-| `FillValue`                 | [Spherical coordinates], [3-vectors]                                                                                                 | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
-| `OrientationRepresentation` | All except [scalar]                                                                                                                  | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation] used to encode orientation information.                                                                             |
-| `ReferenceAxes`             | All except [scalar]                                                                                                                  | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
-| `SphericalHarmonicBasis`    | [Spherical harmonics (SH)]                                                                                                           | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonic coefficients.                                                                                            |
-| `SphericalHarmonicDegree`   | [Spherical harmonics (SH)]                                                                                                           | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
+| **Key name**                | **Relevant [data representations]**                                                                                                                                                                                                                                  | **Description**                                                                                                                                                                                                                                                          |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AntipodalSymmetry`         | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors), [spherical harmonics](#spherical-harmonics), [amplitudes](#amplitudes), [probability distribution functions](#probability-distribution-functions), [parameter vectors](#parameter-vectors) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
+| `Directions`                | [Amplitudes]                                                                                                                                                                                                                                                         | REQUIRED. List. Data are either [spherical coordinates (directions only)](#directions-only) or [3-vectors](#3-vectors) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                  |
+| `FillValue`                 | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors)                                                                                                                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
+| `OrientationRepresentation` | All except [scalar](#scalar)                                                                                                                                                                                                                                         | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
+| `ReferenceAxes`             | All except [scalar](#scalar)                                                                                                                                                                                                                                         | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonic coefficients.                                                                                            |
+| `SphericalHarmonicDegree`   | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
 
-#### Spherical Harmonics (SH) bases
+#### Spherical Harmonics bases
 
 -   `MRtrix3`
 
@@ -272,21 +273,21 @@ intrinsic or extrinsic parameters. 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 future version of the specification.
 
-| Model label | Full Name                                                                                                                                       | [Data representation]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates] image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics (SH)] image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors] image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                           |
-| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions (PDF)]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors] image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar] image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors] 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One scalar image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three scalar images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors] image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes] image<br>OR<br>Single [spherical harmonics (SH)] image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors] image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One scalar image with parameter name "`awf`", representing the estimated axonal water fraction |
+| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#spherical-coordinates) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#spherical-harmonics) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#parameter-vectors) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#parameter-vectors) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                  |
+| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#probability-distribution-functions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#parameter-vectors) image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#parameter-vectors) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One scalar image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three [scalar](#scalar) images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors](#3-vectors) image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes](#amplitudes) image<br>OR<br>Single [spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors](#parameter-vectors) image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One [scalar](#scalar) image with parameter name "`awf`", representing the estimated axonal water fraction |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:
@@ -317,8 +318,8 @@ field depends on the particular model used.
 
 "`Parameters`" fields that may be applicable to multiple models:
 
-| **Key name**     | **Description**                                                                                                                                                                                                                                                                              |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Key name**     | **Description**                                                                                                                                                                                                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | FitMethod        | OPTIONAL. String. The optimisation procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Options are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
 | Iterations       | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                    |
 | OutlierRejection | OPTIONAL. Boolean. Value indicating whether or not rejection of outlier values was performed during fitting of the intrinsic model parameters.                                                                                                                                                         |
@@ -346,8 +347,8 @@ Reserved keywords for models built into the specification are as follows:
         -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
         -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
     -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics (SH) bases] section.
-    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics].
+    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics bases](#spherical-harmonics-bases) section.
+    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics](#spherical-harmonics).
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
 -   `dsi` :
@@ -408,36 +409,37 @@ Reserved keywords for models built into the specification are as follows:
 
 ### Extrinsic model parameters
 
-| `<parameter>` value | Description                                                            | [Data representation] | Possible Model sources                          | Unit or scale                                                  |
-| ------------------- | ---------------------------------------------------------------------- | --------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
-| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `ak`                | Axial kurtosis                                                         | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
-| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | Scalar                | { `csd` }                                       | Unitless                                                       |
-| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
-| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
-| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
-| `evec`              | Eigenvector(s)                                                         | [3-vectors]           | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
-| `fsum`              | Sum of partial volume fractions of stick components                    | Scalar                | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
-| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | Scalar                | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
-| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `mk`                | Mean kurtosis                                                          | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
-| `mode`              | Mode of the tensor                                                     | Scalar                | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                      |
-| `msd`               | Mean-Squared Displacement                    | Scalar                | { `mapmri`, `shore` }                           |                                                      |
-| `pdf`               | Diffusion propagator                                                   | [3-vectors]           |                                       |                                                      |
-| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors]           | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
-| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | Scalar                | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `rk`                | Radial kurtosis                                                        | Scalar                | { `dki`, `wmti` }                               | Unitless                                                       |
-| `rtap`              | Return To Axis Probability                                             | Scalar                | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `rtop`              | Return To Origin Probability                 | Scalar                | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
-| `rtpp`              | Return To Plane Probability                                            | Scalar                | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `tort`              | Tortuosity of extra-cellular space                   | Scalar                | { `dki` }                                       |                                                      |
-
-While not explicitly included in the table above, *any* scalar extrinsic
-parameter can theoretically be combined with a separate source of orientation
-information from the diffusion model in order to produce a
-[directionally-encoded colours (DEC)], [spherical coordinates] or
-[3-vectors] image.
+| `<parameter>` value | Description                                                            | [Data representation]   | Possible Model sources                          | Unit or scale                                                  |
+| ------------------- | ---------------------------------------------------------------------- | ----------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
+| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `ak`                | Axial kurtosis                                                         | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#scalar)       | { `csd` }                                       | Unitless                                                       |
+| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `evec`              | Eigenvector(s)                                                         | [3-vectors](#3-vectors) | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
+| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#scalar)       | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
+| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#scalar)       | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
+| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `mk`                | Mean kurtosis                                                          | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `mode`              | Mode of the tensor                                                     | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `msd`               | Mean-Squared Displacement                                              | [Scalar](#scalar)       | { `mapmri`, `shore` }                           |                                                                |
+| `pdf`               | Diffusion propagator                                                   | [3-vectors](#3-vectors) |                                                 |                                                                |
+| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#3-vectors) | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
+| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `rk`                | Radial kurtosis                                                        | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `rtap`              | Return To Axis Probability                                             | [Scalar](#scalar)       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `rtop`              | Return To Origin Probability                                           | [Scalar](#scalar)       | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
+| `rtpp`              | Return To Plane Probability                                            | [Scalar](#scalar)       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `tort`              | Tortuosity of extra-cellular space                                     | [Scalar](#scalar)       | { `dki` }                                       |                                                                |
+
+While not explicitly included in the table above, *any* [Scalar](#scalar)
+extrinsic parameter can theoretically be combined with a separate source
+of orientation information from the diffusion model in order to produce a
+[directionally-encoded colours (DEC)](#directionally-encoded-colours),
+[spherical coordinates](#spherical-coordinates) or
+[3-vectors](#3-vectors) image.
 
 ## Demonstrative examples
 
@@ -451,7 +453,7 @@ information from the diffusion model in order to produce a
                 sub-01_dti.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors])
+    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#parameter-vectors))
 
     Contents of JSON file:
 
@@ -482,9 +484,9 @@ information from the diffusion model in order to produce a
                 sub-01_csd.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics (SH)])
-    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics (SH)])
-    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics (SH)])
+    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#spherical-harmonics))
+    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
+    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
 
     Contents of file "`sub-01_csd.json`" (common to all intrinsic model parameter images):
 
@@ -544,10 +546,10 @@ information from the diffusion model in order to produce a
                 sub-01_noddi.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors])
+    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#3-vectors))
 
     Contents of file "`sub-01_noddi.json`" (common to all intrinsic model parameter images):
 
@@ -586,11 +588,11 @@ information from the diffusion model in order to produce a
                 sub-01_bs.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar])
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates], distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates], distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
 
     Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
     and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
@@ -668,7 +670,7 @@ should be approximately 3.0.
 
 <a name="tournier2007">\[Tournier2007\]</a>: Tournier et al. 2007
 
-<a name="tuch2004">\[Tuch2004\]</a>: Tuch 1994
+<a name="tuch2004">\[Tuch2004\]</a>: Tuch 2004
 
 <a name="wedeen2008">\[Wedeen2008\]</a>: Wedeen et al. 2008
 

From 1fd477cc5770cbb7d8478dd8b60c5f7d50d80d3c Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 16 Jul 2019 19:06:21 +1000
Subject: [PATCH 05/65] BEP016: More updates of internal header links

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index c82c30a2..9391183b 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -195,13 +195,13 @@ which has its own unique requirements with respect to:
 
 ### Orientation specification
 
-| **Key name**                | **Relevant [data representations]**                                                                                                                                                                                                                                  | **Description**                                                                                                                                                                                                                                                          |
+| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                                                                           | **Description**                                                                                                                                                                                                                                                          |
 | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `AntipodalSymmetry`         | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors), [spherical harmonics](#spherical-harmonics), [amplitudes](#amplitudes), [probability distribution functions](#probability-distribution-functions), [parameter vectors](#parameter-vectors) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
-| `Directions`                | [Amplitudes]                                                                                                                                                                                                                                                         | REQUIRED. List. Data are either [spherical coordinates (directions only)](#directions-only) or [3-vectors](#3-vectors) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                  |
+| `Directions`                | [Amplitudes](#amplitudes)                                                                                                                                                                                                                                            | REQUIRED. List. Data are either [spherical coordinates (directions only)](#directions-only) or [3-vectors](#3-vectors) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                  |
 | `FillValue`                 | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors)                                                                                                                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
-| `OrientationRepresentation` | All except [scalar](#scalar)                                                                                                                                                                                                                                         | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
-| `ReferenceAxes`             | All except [scalar](#scalar)                                                                                                                                                                                                                                         | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
+| `OrientationRepresentation` | All except scalar                                                                                                                                                                                                                                                    | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
+| `ReferenceAxes`             | All except scalar                                                                                                                                                                                                                                                    | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
 | `SphericalHarmonicBasis`    | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonic coefficients.                                                                                            |
 | `SphericalHarmonicDegree`   | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
 
@@ -562,8 +562,6 @@ of orientation information from the diffusion model in order to produce a
 
     Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
 
-    ***TODO Don't know what reference axes are used by default for NODDI***
-
     ```JSON
     {
         "OrientationRepresentation": "3vector",

From a46260328dfa187ff143192c219bcf5b8458afe9 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 16 Aug 2019 21:46:28 +1000
Subject: [PATCH 06/65] BEP016: Minor tweaks from first feedback round

- More clarity of distinction between requisite and optional files in output directory.
- Try using 3 spaces rather than 4 in non-code indentation; partly to try to get tables within dot point lists to render correctly, partly to improve editor software syntax highlighting.
---
 .../05-diffusion-derivatives.md               | 784 +++++++++---------
 1 file changed, 393 insertions(+), 391 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 9391183b..7c3b249f 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -47,26 +47,26 @@ informative representations of the diffusion process and the underlying
 biological structure. A wide range of such models are available, each of
 which has its own unique requirements with respect to:
 
--   The input parameters required to define / constrain the model;
+-  The input parameters required to define / constrain the model;
 
--   The appropriate data representation in which the resulting
-    parameters estimated of / from the model are stored on the filesystem;
+-  The appropriate data representation in which the resulting
+   parameters estimated of / from the model are stored on the filesystem;
 
--   The requirements for encapsulation and complete representation of
-    derived orientation information, which is a key strength of diffusion
-    MRI but presents unique challenges for correct interpretation.
+-  The requirements for encapsulation and complete representation of
+   derived orientation information, which is a key strength of diffusion
+   MRI but presents unique challenges for correct interpretation.
 
 ### Parameter terminology
 
-1.  *Intrinsic* parameter: Item that is the direct result of fitting
-    the diffusion model to the empirical diffusion-weighted data.
+1. *Intrinsic* parameter: Item that is the direct result of fitting
+   the diffusion model to the empirical diffusion-weighted data.
 
-1.  *Input* parameter: Item that influences the conformation of the
-    diffusion model to the empirical diffusion-weighted data.
+1. *Input* parameter: Item that influences the conformation of the
+   diffusion model to the empirical diffusion-weighted data.
 
-1.  *Extrinsic* parameter: Item that can be calculated from prior
-    estimated intrinsic model parameters, without necessitating reference
-    to the empirical diffusion-weighted data.
+1. *Extrinsic* parameter: Item that can be calculated from prior
+   estimated intrinsic model parameters, without necessitating reference
+   to the empirical diffusion-weighted data.
 
 ### File names
 
@@ -83,115 +83,117 @@ which has its own unique requirements with respect to:
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
 ```
 
--   File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-    provides basic model information and [input model parameters](#input-model-parameters).
+-  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
+   provides basic model information and [input model parameters](#input-model-parameters).
 
--   OPTIONAL file "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
-    provides only information or parameters relevant to derivation of the
-    relevant [extrinsic model parameter](#extrinsic-model-parameters) based
-    on prior estimates of [intrinsic model parameters](#intrinsic-model-parameters).
+-  OPTIONAL file "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+   provides only information or parameters relevant to derivation of the
+   relevant [extrinsic model parameter](#extrinsic-model-parameters) based
+   on prior estimates of [intrinsic model parameters](#intrinsic-model-parameters).
 
--   If all [intrinsic model parameters](#intrinsic-model-parameters) are
-    contained within a single image file, field "`_parameter-*`" MUST be
-    omitted (for intrinsic parameter image only):
+-  If all [intrinsic model parameters](#intrinsic-model-parameters) are
+   contained within a single image file, field "`_parameter-*`" MUST be
+   omitted (for intrinsic parameter image only):
 
-    ```Text
-    <pipeline_name>/
-        sub-<participant_label>/
-            dwi/
-                <source_keywords>[_space-<space>][_desc-<label>]_<model>.nii[.gz]
-                <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
-    ```
+   ```Text
+   <pipeline_name>/
+       sub-<participant_label>/
+           dwi/
+               <source_keywords>[_space-<space>][_desc-<label>]_<model>.nii[.gz]
+               <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+   ```
 
 ### Data representations
 
-1.  Scalars
+1. Scalars
 
-    Any model parameter image (whether intrinsic or extrinsic) where a
-    solitary value is defined in each 3D image voxel is referred to here as a
-    "scalar" image.
+   Any model parameter image (whether intrinsic or extrinsic) where a
+   solitary value is defined in each 3D image voxel is referred to here as a
+   "scalar" image.
 
-1.  Directionally-Encoded Colours
+1. Directionally-Encoded Colours
 
-    4D image with three volumes, intended to be interpreted as red, green
-    and blue colour intensities for visualisation
-    \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
-    values. Abbreviation "DEC" is regularly used to refer to such data.
+   4D image with three volumes, intended to be interpreted as red, green
+   and blue colour intensities for visualisation
+   \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
+   values. Abbreviation "DEC" is regularly used to refer to such data.
 
-1.  Spherical coordinates
+1. Spherical coordinates
 
-    4D image where data across volumes within each voxel encode one or
-    more discrete orientations using polar angles, optionally exploiting
-    the distance from origin to encode the value of some parameter.
+   4D image where data across volumes within each voxel encode one or
+   more discrete orientations using polar angles, optionally exploiting
+   the distance from origin to encode the value of some parameter.
 
-    1. Value per direction
+   1. Value per direction
 
-        Each consecutive triplet of image volumes encodes a spherical
-        coordinate, using ISO convention for both the order of parameters
-        and reference frame for angles:
+      Each consecutive triplet of image volumes encodes a spherical
+      coordinate, using ISO convention for both the order of parameters
+      and reference frame for angles:
 
-        1.  Distance from origin; value of embedded parameter SHOULD be
-            indicated in "`_parameter-*`" filename field;
+      1. Distance from origin; value of embedded parameter SHOULD be
+         indicated in "`_parameter-*`" filename field;
 
-        1.  Inclination / polar angle, in radians, relative to the zenith
-            direction being the positive direction of the *third* reference
-            axis (see [orientation specification](#orientation-specification));
+      1. Inclination / polar angle, in radians, relative to the zenith
+         direction being the positive direction of the *third* reference
+         axis (see [orientation specification](#orientation-specification));
 
-        1.  Azimuth angle, in radians, orthogonal to the zenith direction,
-            with value of 0.0 corresponding to the *first* reference axis
-            (see [orientation specification](#orientation-specification)),
-            increasing according to the right-hand rule about the zenith
-            direction.
+      1. Azimuth angle, in radians, orthogonal to the zenith direction,
+         with value of 0.0 corresponding to the *first* reference axis
+         (see [orientation specification](#orientation-specification)),
+         increasing according to the right-hand rule about the zenith
+         direction.
 
-        Number of image volumes is equal to (3x*N*), where *N* is the maximum
-        number of discrete orientations in any voxel in the image.
+      Number of image volumes is equal to (3x*N*), where *N* is the maximum
+      number of discrete orientations in any voxel in the image.
 
-    1.  Directions only
+   1. Directions only
 
-        Each consecutive pair of image volumes encodes inclination /
-        azimuth pairs, with order & convention identical to that above
-        (equivalent to spherical coordinate with assumed unity distance from
-        origin).
+      Each consecutive pair of image volumes encodes inclination /
+      azimuth pairs, with order & convention identical to that above
+      (equivalent to spherical coordinate with assumed unity distance from
+      origin).
 
-        Number of image volumes is equal to (2x*N*), where *N* is the maximum
-        number of discrete orientations in any voxel in the image.
+      Number of image volumes is equal to (2x*N*), where *N* is the maximum
+      number of discrete orientations in any voxel in the image.
 
-1.  3-Vectors
+1. 3-Vectors
 
-    4D image where data across volumes within each voxel encode one or
-    more discrete orientations using triplets of axis dot products.
+   4D image where data across volumes within each voxel encode one or
+   more discrete orientations using triplets of axis dot products.
 
-    If not all 3-vectors are of unit norm, parameter encoded as vector
-    norm SHOULD be indicated in "`_parameter-*`" filename field.
+   If not all 3-vectors are of unit norm, parameter encoded as vector
+   norm SHOULD be indicated in "`_parameter-*`" filename field.
 
-    Number of image volumes is equal to (3x*N*), where *N* is the maximum
-    number of discrete orientations in any voxel in the image.
+   Number of image volumes is equal to (3x*N*), where *N* is the maximum
+   number of discrete orientations in any voxel in the image.
 
-1.  Spherical Harmonics
+1. Spherical Harmonics
 
-    4D image where data across volumes within each voxel represent a
-    continuous function spanning the 2-sphere as coefficient values using a
-    spherical harmonic (SH) basis.
+   4D image where data across volumes within each voxel represent a
+   continuous function spanning the 2-sphere as coefficient values using a
+   spherical harmonic (SH) basis.
 
-    Number of image volumes depends on the spherical harmonic basis employed,
-    and the maximal spherical harmonic degree *l<sub>max</sub>*.
+   Number of image volumes depends on the spherical harmonic basis employed,
+   and the maximal spherical harmonic degree *l<sub>max</sub>*.
 
-1.  Amplitudes
+1. Amplitudes
 
-    4D image where data across volumes within each voxel represent
-    amplitudes of a discrete function spanning the 2-sphere.
+   4D image where data across volumes within each voxel represent
+   amplitudes of a discrete function spanning the 2-sphere.
 
-    Number of image volumes corresponds to the number of discrete directions
-    on the unit sphere along which samples for the function in each voxel
-    are provided.
+   Number of image volumes corresponds to the number of discrete directions
+   on the unit sphere along which samples for the function in each voxel
+   are provided.
 
-1.  Probability Distribution Functions
+1. Probability Distribution Functions
 
-1.  Parameter vectors
+   ***TODO***
 
-    4D image containing, for every image voxel, data corresponding to some
-    set of model parameters, the names and order of which are defined within
-    the [intrinsic model parameters](#intrinsic-model-parameters) section.
+1. Parameter vectors
+
+   4D image containing, for every image voxel, data corresponding to some
+   set of model parameters, the names and order of which are defined within
+   the [intrinsic model parameters](#intrinsic-model-parameters) section.
 
 ### Orientation specification
 
@@ -207,63 +209,63 @@ which has its own unique requirements with respect to:
 
 #### Spherical Harmonics bases
 
--   `MRtrix3`
+-  `MRtrix3`
 
-    -   Antipodally symmetric: all basis functions with odd degree are
-        assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
+   -  Antipodally symmetric: all basis functions with odd degree are
+      assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
 
-    -   Functions assumed to be real: conjugate symmetry is assumed, i.e.
-        *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
-        conjugate.
+   -  Functions assumed to be real: conjugate symmetry is assumed, i.e.
+      *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
+      conjugate.
 
-    -   Mapping of image volumes to spherical harmonic basis function
-        coefficients:
+   -  Mapping of image volumes to spherical harmonic basis function
+      coefficients:
 
-        | **Volume** | **Coefficient**                   |
-        | ---------- | --------------------------------- |
-        | 0          | *l* = 0, *m* = 0                  |
-        | 1          | *l* = 2, *m* = 2 (imaginary part) |
-        | 2          | *l* = 2, *m* = 1 (imaginary part) |
-        | 3          | *l* = 2, *m* = 0                  |
-        | 4          | *l* = 2, *m* = 1 (real part)      |
-        | 5          | *l* = 2, *m* = 2 (real part)      |
-        | 6          | *l* = 4, *m* = 4 (imaginary part) |
-        | 7          | *l* = 4, *m* = 3 (imaginary part) |
-        | ...        | etc.                              |
+      | **Volume** | **Coefficient**                   |
+      | ---------- | --------------------------------- |
+      | 0          | *l* = 0, *m* = 0                  |
+      | 1          | *l* = 2, *m* = 2 (imaginary part) |
+      | 2          | *l* = 2, *m* = 1 (imaginary part) |
+      | 3          | *l* = 2, *m* = 0                  |
+      | 4          | *l* = 2, *m* = 1 (real part)      |
+      | 5          | *l* = 2, *m* = 2 (real part)      |
+      | 6          | *l* = 4, *m* = 4 (imaginary part) |
+      | 7          | *l* = 4, *m* = 3 (imaginary part) |
+      | ...        | etc.                              |
 
-    -   Normalisation: ***TODO***
+   -  Normalisation: ***TODO***
 
-    Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
-    and number of image volumes *N*:
+   -  Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+      and number of image volumes *N*:
 
-        *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+      *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-        | ***l<sub>max</sub>*** | ***N*** |
-        | --------------------- | ------- |
-        | 0                     | 1       |
-        | 2                     | 6       |
-        | 4                     | 15      |
-        | 6                     | 28      |
-        | 8                     | 45      |
-        | ...                   | etc.    |
+      | ***l<sub>max</sub>*** | ***N*** |
+      | --------------------- | ------- |
+      | 0                     | 1       |
+      | 2                     | 6       |
+      | 4                     | 15      |
+      | 6                     | 28      |
+      | 8                     | 45      |
+      | ...                   | etc.    |
 
-    Relationship between maximal degree of *zonal* spherical harmonic
-    function (spherical harmonics function where all *m* != 0 terms are
-    assumed to be zero; used for e.g. response function definition) and
-    number of coefficients *N*:
+   -  Relationship between maximal degree of *zonal* spherical harmonic
+      function (spherical harmonics function where all *m* != 0 terms are
+      assumed to be zero; used for e.g. response function definition) and
+      number of coefficients *N*:
 
-        *N* = 1 + (*l<sub>max</sub>* / 2)
+      *N* = 1 + (*l<sub>max</sub>* / 2)
 
-        | ***l<sub>max</sub>*** | ***N*** |
-        | --------------------- | ------- |
-        | 0                     | 1       |
-        | 2                     | 2       |
-        | 4                     | 3       |
-        | 6                     | 4       |
-        | 8                     | 5       |
-        | ...                   | etc.    |
+      | ***l<sub>max</sub>*** | ***N*** |
+      | --------------------- | ------- |
+      | 0                     | 1       |
+      | 2                     | 2       |
+      | 4                     | 3       |
+      | 6                     | 4       |
+      | 8                     | 5       |
+      | ...                   | etc.    |
 
- -   `Descoteaux`
+-  `Descoteaux`
 
 ### Intrinsic model parameters
 
@@ -327,85 +329,85 @@ field depends on the particular model used.
 
 Reserved keywords for models built into the specification are as follows:
 
--   `bs` :
-
-    -   `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
-    -   `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
-    -   `ModelBall`: String. Model used to describe the "ball" component in the model.
-    -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
-
--   `csa` :
-
-    -   `SphericalHarmonicOrder` : value
-    -   `Smoothing` : value
-    -   `Basis` : value
-
--   `csd`:
-
-    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
-    -   `ResponseFunctionZSH`: Two options:
-        -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
-        -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
-    -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics bases](#spherical-harmonics-bases) section.
-    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics](#spherical-harmonics).
-    -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
-
--   `dsi` :
-
-    -   `GridSize` : value
-    -   `RStart` : value
-    -   `RStep` : value
-    -   `REnd` : value
-    -   `FilterWidth` : value
-
--   `dti` :
-
-    -   `RESTORESigma`: Float
-
--   `forecast` :
-
-    -   `Sphere` : value
-    -   `DecAlg` : value
-    -   `LambdaLb` : value
-    -   `SphericalHarmonicsOrder` : value
-
--   `mapmri` :
-
-    -   `RadialOrder` : value
-    -   `LaplacianRegularization` : bool
-    -   `LaplacianWeighting` : value
-    -   `PositivityConstraint` : bool
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
-    -   `AnisotropicScaling` : bool
-    -   `EigenvalueThreshold` : value
-    -   `PosGrid` : value
-    -   `BvalThreshold` : value
-    -   `DTIScaleEstimation` : bool
-    -   `StaticDiffusivity` : value
-
--   `noddi`:
-
-    -   `DPar` : value
-    -   `DIso` : value
-    -   `Lambda1` : value
-    -   `Lambda2` : value
-
--   `shore` :
-
-    -   `RadialOrder` : value
-    -   `Zeta` : value
-    -   `LambdaN` : value
-    -   `LambdaL` : value
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
+-  `bs` :
+
+   -  `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
+   -  `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
+   -  `ModelBall`: String. Model used to describe the "ball" component in the model.
+   -  `ModelSticks`: String. Model used to describe the "stick" component in the model.
+
+-  `csa` :
+
+   -  `SphericalHarmonicOrder` : value
+   -  `Smoothing` : value
+   -  `Basis` : value
+
+-  `csd`:
+
+   -  `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
+   -  `ResponseFunctionZSH`: Two options:
+      -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
+      -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
+   -  `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
+   -  `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics bases](#spherical-harmonics-bases) section.
+   -  `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics](#spherical-harmonics).
+   -  `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
+
+-  `dsi` :
+
+   -  `GridSize` : value
+   -  `RStart` : value
+   -  `RStep` : value
+   -  `REnd` : value
+   -  `FilterWidth` : value
+
+-  `dti` :
+
+   -  `RESTORESigma`: Float
+
+-  `forecast` :
+
+   -  `Sphere` : value
+   -  `DecAlg` : value
+   -  `LambdaLb` : value
+   -  `SphericalHarmonicsOrder` : value
+
+-  `mapmri` :
+
+   -  `RadialOrder` : value
+   -  `LaplacianRegularization` : bool
+   -  `LaplacianWeighting` : value
+   -  `PositivityConstraint` : bool
+   -  `Tau` : value
+   -  `ConstrainE0` : value
+   -  `PositiveConstraint` : value
+   -  `PosGrid` : value
+   -  `PosRadius` : value
+   -  `AnisotropicScaling` : bool
+   -  `EigenvalueThreshold` : value
+   -  `PosGrid` : value
+   -  `BvalThreshold` : value
+   -  `DTIScaleEstimation` : bool
+   -  `StaticDiffusivity` : value
+
+-  `noddi`:
+
+   -  `DPar` : value
+   -  `DIso` : value
+   -  `Lambda1` : value
+   -  `Lambda2` : value
+
+-  `shore` :
+
+   -  `RadialOrder` : value
+   -  `Zeta` : value
+   -  `LambdaN` : value
+   -  `LambdaL` : value
+   -  `Tau` : value
+   -  `ConstrainE0` : value
+   -  `PositiveConstraint` : value
+   -  `PosGrid` : value
+   -  `PosRadius` : value
 
 ### Extrinsic model parameters
 
@@ -443,184 +445,184 @@ of orientation information from the diffusion model in order to produce a
 
 ## Demonstrative examples
 
--   A basic Diffusion Tensor fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_dti.nii.gz
-                sub-01_dti.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#parameter-vectors))
-
-    Contents of JSON file:
-
-    ```JSON
-    {
-        "Model": "Diffusion Tensor",
-        "OrientationRepresentation": "param",
-        "ReferenceAxes": "xyz",
-        "Parameters": {
-            "FitMethod": "ols",
-            "OutlierRejection": False
-        }
-    }
-    ```
-
--   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_desc-wm_csd.nii.gz
-                sub-01_desc-wm_csd.json
-                sub-01_desc-gm_csd.nii.gz
-                sub-01_desc-gm_csd.json
-                sub-01_desc-csf_csd.nii.gz
-                sub-01_desc-csf_csd.json
-                sub-01_csd.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#spherical-harmonics))
-    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
-    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
-
-    Contents of file "`sub-01_csd.json`" (common to all intrinsic model parameter images):
-
-    ```JSON
-    {
-        "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-        "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
-        "Shells": [ 0, 1000, 2000, 3000 ],
-        "Parameters": {
-            "SphericalHarmonicBasis": "MRtrix3",
-            "NonNegativityConstraint": "hard"
-        }
-    }
-    ```
-
-    Contents of JSON file "`sub-01_desc-wm_csd.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "sh",
-        "ReferenceAxes": "xyz",
-        "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
-                                 [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
-                                 [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
-                                 [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
-        "SphericalHarmonicDegree": 8,
-        "Tissue": "White matter"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_desc-gm_csd.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "sh",
-        "ReferenceAxes": "xyz",
-        "ResponseFunctionZSH": [ [ 1041.0 ],
-                                 [ 436.6 ],
-                                 [ 224.9 ],
-                                 [ 128.8 ] ],
-        "SphericalHarmonicDegree": 0,
-        "Tissue": "Grey matter"
-    }
-    ```
-
--   A NODDI fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_parameter-icvf_noddi.nii.gz
-                sub-01_parameter-isovf_noddi.nii.gz
-                sub-01_parameter-od_noddi.nii.gz
-                sub-01_parameter-direction_noddi.nii.gz
-                sub-01_parameter-direction_noddi.json
-                sub-01_noddi.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#3-vectors))
-
-    Contents of file "`sub-01_noddi.json`" (common to all intrinsic model parameter images):
-
-    ```JSON
-    {
-        "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
-        "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "3vector",
-        "ReferenceAxes": "???"
-    }
-    ```
-
--   An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
-    bootstrap realisations):
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_desc-mean_parameter-bzero_bs.nii.gz
-                sub-01_desc-mean_parameter-dmean_bs.nii.gz
-                sub-01_desc-mean_parameter-dstd_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.json
-                sub-01_desc-merged_parameter-sticks_bs.nii.gz
-                sub-01_desc-merged_parameter-sticks_bs.json
-                sub-01_bs.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
-
-    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
-    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
-    files are identical):
-
-    ```JSON
-    {
-        "OrientationRepresentation": "spherical",
-        "ReferenceAxes": "ijk"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_bs.json`":
-
-    ```JSON
-    {
-        "Model": "Ball-And-Sticks model using FSL bedpostx",
-        "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-        "Parameters": {
-            "ARDFudgeFactor": 1.0,
-            "Fibers": 3,
-            "Samples": 50
-        },
-        "BootstrapParameters": {
-            "Burnin": 1000,
-            "Jumps": 1250,
-            "SampleEvery": 25
-        }
-    }
-    ```
+-  A basic Diffusion Tensor fit:
+
+   ```Text
+   my_diffusion_pipeline/
+       sub-01/
+           dwi/
+               sub-01_dti.nii.gz
+               sub-01_dti.json
+   ```
+
+   Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#parameter-vectors))
+
+   Contents of JSON file:
+
+   ```JSON
+   {
+       "Model": "Diffusion Tensor",
+       "OrientationRepresentation": "param",
+       "ReferenceAxes": "xyz",
+       "Parameters": {
+           "FitMethod": "ols",
+           "OutlierRejection": False
+       }
+   }
+   ```
+
+-  A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+
+   ```Text
+   my_diffusion_pipeline/
+       sub-01/
+           dwi/
+               sub-01_desc-wm_csd.nii.gz
+               sub-01_desc-wm_csd.json
+               sub-01_desc-gm_csd.nii.gz
+               sub-01_desc-gm_csd.json
+               sub-01_desc-csf_csd.nii.gz
+               sub-01_desc-csf_csd.json
+               sub-01_csd.json
+   ```
+
+   Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#spherical-harmonics))
+   Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
+   Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
+
+   Contents of file "`sub-01_csd.json`" (common to all intrinsic model parameter images):
+
+   ```JSON
+   {
+       "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+       "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+       "Shells": [ 0, 1000, 2000, 3000 ],
+       "Parameters": {
+           "SphericalHarmonicBasis": "MRtrix3",
+           "NonNegativityConstraint": "hard"
+       }
+   }
+   ```
+
+   Contents of JSON file "`sub-01_desc-wm_csd.json`":
+
+   ```JSON
+   {
+       "OrientationRepresentation": "sh",
+       "ReferenceAxes": "xyz",
+       "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
+                                [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
+                                [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
+                                [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
+       "SphericalHarmonicDegree": 8,
+       "Tissue": "White matter"
+   }
+   ```
+
+   Contents of JSON file "`sub-01_desc-gm_csd.json`":
+
+   ```JSON
+   {
+       "OrientationRepresentation": "sh",
+       "ReferenceAxes": "xyz",
+       "ResponseFunctionZSH": [ [ 1041.0 ],
+                                [ 436.6 ],
+                                [ 224.9 ],
+                                [ 128.8 ] ],
+       "SphericalHarmonicDegree": 0,
+       "Tissue": "Grey matter"
+   }
+   ```
+
+-  A NODDI fit:
+
+   ```Text
+   my_diffusion_pipeline/
+       sub-01/
+           dwi/
+               sub-01_parameter-icvf_noddi.nii.gz
+               sub-01_parameter-isovf_noddi.nii.gz
+               sub-01_parameter-od_noddi.nii.gz
+               sub-01_parameter-direction_noddi.nii.gz
+               sub-01_parameter-direction_noddi.json
+               sub-01_noddi.json
+   ```
+
+   Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#3-vectors))
+
+   Contents of file "`sub-01_noddi.json`" (common to all intrinsic model parameter images):
+
+   ```JSON
+   {
+       "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+       "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
+   }
+   ```
+
+   Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
+
+   ```JSON
+   {
+       "OrientationRepresentation": "3vector",
+       "ReferenceAxes": "???"
+   }
+   ```
+
+-  An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
+   bootstrap realisations):
+
+   ```Text
+   my_diffusion_pipeline/
+       sub-01/
+           dwi/
+               sub-01_desc-mean_parameter-bzero_bs.nii.gz
+               sub-01_desc-mean_parameter-dmean_bs.nii.gz
+               sub-01_desc-mean_parameter-dstd_bs.nii.gz
+               sub-01_desc-mean_parameter-sticks_bs.nii.gz
+               sub-01_desc-mean_parameter-sticks_bs.json
+               sub-01_desc-merged_parameter-sticks_bs.nii.gz
+               sub-01_desc-merged_parameter-sticks_bs.json
+               sub-01_bs.json
+   ```
+
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction)
+   Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+
+   Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
+   and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
+   files are identical):
+
+   ```JSON
+   {
+       "OrientationRepresentation": "spherical",
+       "ReferenceAxes": "ijk"
+   }
+   ```
+
+   Contents of JSON file "`sub-01_bs.json`":
+
+   ```JSON
+   {
+       "Model": "Ball-And-Sticks model using FSL bedpostx",
+       "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+       "Parameters": {
+           "ARDFudgeFactor": 1.0,
+           "Fibers": 3,
+           "Samples": 50
+       },
+       "BootstrapParameters": {
+           "Burnin": 1000,
+           "Jumps": 1250,
+           "SampleEvery": 25
+       }
+   }
+   ```
 
 -----
 

From 021cfd53058867fa58115f84eddf10b1df66b3d2 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 16 Aug 2019 22:17:05 +1000
Subject: [PATCH 07/65] BEP016: Try to get links working within tables

---
 .../05-diffusion-derivatives.md               | 205 ++++++++++--------
 1 file changed, 109 insertions(+), 96 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 7c3b249f..b270bc13 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -58,15 +58,21 @@ which has its own unique requirements with respect to:
 
 ### Parameter terminology
 
-1. *Intrinsic* parameter: Item that is the direct result of fitting
-   the diffusion model to the empirical diffusion-weighted data.
+1. <a name="parameter-intrinsic">*Intrinsic*</a> model parameter:
 
-1. *Input* parameter: Item that influences the conformation of the
-   diffusion model to the empirical diffusion-weighted data.
+   Item that is the direct result of fitting the diffusion model to the
+   empirical diffusion-weighted data.
 
-1. *Extrinsic* parameter: Item that can be calculated from prior
-   estimated intrinsic model parameters, without necessitating reference
-   to the empirical diffusion-weighted data.
+1. <a name="parameter-input">*Input*</a> model parameter:
+
+   Item that influences the conformation of the diffusion model to the
+   empirical diffusion-weighted data.
+
+1. <a name="parameter-extrinsic">*Extrinsic*</a> model parameter:
+
+   Item that can be calculated from prior estimated intrinsic model
+   parameters, without necessitating reference to the empirical
+   diffusion-weighted data.
 
 ### File names
 
@@ -77,6 +83,7 @@ which has its own unique requirements with respect to:
             <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam1>_<model>.nii[.gz]
             <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam2>_<model>.nii[.gz]
             <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.nii[.gz]]
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.json]
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.nii[.gz]]
@@ -84,14 +91,19 @@ which has its own unique requirements with respect to:
 ```
 
 -  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-   provides basic model information and [input model parameters](#input-model-parameters).
+   provides basic model information and [input](#parameter-input)
+   model parameters.
 
--  OPTIONAL file "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
-   provides only information or parameters relevant to derivation of the
-   relevant [extrinsic model parameter](#extrinsic-model-parameters) based
-   on prior estimates of [intrinsic model parameters](#intrinsic-model-parameters).
+-  Images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
+   MAY be defined if additional [extrinsic](#parameter-extrinsic)
+   model parameters beyond the compulsory [intrinsic](#parameter-intrinsic)
+   parameters are to be provided.
 
--  If all [intrinsic model parameters](#intrinsic-model-parameters) are
+-  OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+   may provide only information or parameters relevant to derivation of each
+   relevant [extrinsic](#parameter-extrinsic) model parameter image.
+
+-  If all [intrinsic](#parameter-intrinsic) model parameters are
    contained within a single image file, field "`_parameter-*`" MUST be
    omitted (for intrinsic parameter image only):
 
@@ -105,20 +117,20 @@ which has its own unique requirements with respect to:
 
 ### Data representations
 
-1. Scalars
+1. <a name="data-scalar">*Scalars*</a>:
 
    Any model parameter image (whether intrinsic or extrinsic) where a
    solitary value is defined in each 3D image voxel is referred to here as a
    "scalar" image.
 
-1. Directionally-Encoded Colours
+1. <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
 
    4D image with three volumes, intended to be interpreted as red, green
    and blue colour intensities for visualisation
    \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
-   values. Abbreviation "DEC" is regularly used to refer to such data.
+   values.
 
-1. Spherical coordinates
+1. <a name="data-spherical">*Spherical coordinates*</a>:
 
    4D image where data across volumes within each voxel encode one or
    more discrete orientations using polar angles, optionally exploiting
@@ -156,7 +168,7 @@ which has its own unique requirements with respect to:
       Number of image volumes is equal to (2x*N*), where *N* is the maximum
       number of discrete orientations in any voxel in the image.
 
-1. 3-Vectors
+1. <a name="data-3vector">*3-Vectors*</a>:
 
    4D image where data across volumes within each voxel encode one or
    more discrete orientations using triplets of axis dot products.
@@ -167,16 +179,16 @@ which has its own unique requirements with respect to:
    Number of image volumes is equal to (3x*N*), where *N* is the maximum
    number of discrete orientations in any voxel in the image.
 
-1. Spherical Harmonics
+1. <a name="data-sh">*Spherical Harmonics (SH)*</a>:
 
    4D image where data across volumes within each voxel represent a
    continuous function spanning the 2-sphere as coefficient values using a
-   spherical harmonic (SH) basis.
+   spherical harmonics basis.
 
    Number of image volumes depends on the spherical harmonic basis employed,
    and the maximal spherical harmonic degree *l<sub>max</sub>*.
 
-1. Amplitudes
+1. <a name="data-amp">*Amplitudes*</a>:
 
    4D image where data across volumes within each voxel represent
    amplitudes of a discrete function spanning the 2-sphere.
@@ -185,27 +197,27 @@ which has its own unique requirements with respect to:
    on the unit sphere along which samples for the function in each voxel
    are provided.
 
-1. Probability Distribution Functions
+1. <a name="data-pdf">*Probability Distribution Functions (PDFs)*</a>:
 
    ***TODO***
 
-1. Parameter vectors
+1. <a name="data-param">*Parameter vectors*</a>:
 
    4D image containing, for every image voxel, data corresponding to some
    set of model parameters, the names and order of which are defined within
-   the [intrinsic model parameters](#intrinsic-model-parameters) section.
+   the [intrinsic](#parameter-intrinsic) model parameters section.
 
 ### Orientation specification
 
-| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                                                                           | **Description**                                                                                                                                                                                                                                                          |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `AntipodalSymmetry`         | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors), [spherical harmonics](#spherical-harmonics), [amplitudes](#amplitudes), [probability distribution functions](#probability-distribution-functions), [parameter vectors](#parameter-vectors) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
-| `Directions`                | [Amplitudes](#amplitudes)                                                                                                                                                                                                                                            | REQUIRED. List. Data are either [spherical coordinates (directions only)](#directions-only) or [3-vectors](#3-vectors) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                  |
-| `FillValue`                 | [Spherical coordinates](#spherical-coordinates), [3-vectors](#3-vectors)                                                                                                                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
-| `OrientationRepresentation` | All except scalar                                                                                                                                                                                                                                                    | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
-| `ReferenceAxes`             | All except scalar                                                                                                                                                                                                                                                    | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonic coefficients.                                                                                            |
-| `SphericalHarmonicDegree`   | [Spherical harmonics](#spherical-harmonics)                                                                                                                                                                                                                          | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
+| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                                          |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
+| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                |
+| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
+| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
+| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                           |
+| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
 
 #### Spherical Harmonics bases
 
@@ -267,6 +279,8 @@ which has its own unique requirements with respect to:
 
 -  `Descoteaux`
 
+   ***TODO***
+
 ### Intrinsic model parameters
 
 The following models are codified within the specification, and the model
@@ -275,21 +289,21 @@ intrinsic or extrinsic parameters. 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 future version of the specification.
 
-| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#spherical-coordinates) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#spherical-harmonics) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#parameter-vectors) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#parameter-vectors) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                  |
-| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#probability-distribution-functions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#parameter-vectors) image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#parameter-vectors) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One scalar image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three [scalar](#scalar) images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors](#3-vectors) image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes](#amplitudes) image<br>OR<br>Single [spherical harmonics](#spherical-harmonics) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors](#parameter-vectors) image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One [scalar](#scalar) image with parameter name "`awf`", representing the estimated axonal water fraction |
+| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                              |
+| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#data-pdf)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#data-param) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One [scalar](#data-scalar) image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three [scalar](#data-scalar) images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors](#data-3vector) image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes](#data-amp) image<br>OR<br>Single [spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors](#data-param) image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One [scalar](#data-scalar) image with parameter name "`awf`", representing the estimated axonal water fraction |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:
@@ -349,8 +363,8 @@ Reserved keywords for models built into the specification are as follows:
       -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
       -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
    -  `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-   -  `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [Spherical harmonics bases](#spherical-harmonics-bases) section.
-   -  `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics](#spherical-harmonics).
+   -  `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+   -  `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
    -  `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
 -  `dsi` :
@@ -411,37 +425,36 @@ Reserved keywords for models built into the specification are as follows:
 
 ### Extrinsic model parameters
 
-| `<parameter>` value | Description                                                            | [Data representation]   | Possible Model sources                          | Unit or scale                                                  |
-| ------------------- | ---------------------------------------------------------------------- | ----------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
-| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `ak`                | Axial kurtosis                                                         | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#scalar)       | { `csd` }                                       | Unitless                                                       |
-| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `evec`              | Eigenvector(s)                                                         | [3-vectors](#3-vectors) | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
-| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#scalar)       | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
-| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#scalar)       | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
-| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `mk`                | Mean kurtosis                                                          | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `mode`              | Mode of the tensor                                                     | [Scalar](#scalar)       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `msd`               | Mean-Squared Displacement                                              | [Scalar](#scalar)       | { `mapmri`, `shore` }                           |                                                                |
-| `pdf`               | Diffusion propagator                                                   | [3-vectors](#3-vectors) |                                                 |                                                                |
-| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#3-vectors) | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
-| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#scalar)       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `rk`                | Radial kurtosis                                                        | [Scalar](#scalar)       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `rtap`              | Return To Axis Probability                                             | [Scalar](#scalar)       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `rtop`              | Return To Origin Probability                                           | [Scalar](#scalar)       | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
-| `rtpp`              | Return To Plane Probability                                            | [Scalar](#scalar)       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `tort`              | Tortuosity of extra-cellular space                                     | [Scalar](#scalar)       | { `dki` }                                       |                                                                |
-
-While not explicitly included in the table above, *any* [Scalar](#scalar)
-extrinsic parameter can theoretically be combined with a separate source
-of orientation information from the diffusion model in order to produce a
-[directionally-encoded colours (DEC)](#directionally-encoded-colours),
-[spherical coordinates](#spherical-coordinates) or
-[3-vectors](#3-vectors) image.
+| `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources                          | Unit or scale                                                  |
+| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
+| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `ak`                | Axial kurtosis                                                         | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#data-scalar)                       | { `csd` }                                       | Unitless                                                       |
+| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
+| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#data-scalar)                       | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
+| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#data-scalar)                       | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
+| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `mk`                | Mean kurtosis                                                          | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
+| `msd`               | Mean-Squared Displacement                                              | [Scalar](#data-scalar)                       | { `mapmri`, `shore` }                           |                                                                |
+| `pdf`               | Diffusion propagator                                                   | [3-vectors](#data-3vector)                   |                                                 |                                                                |
+| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#data-3vector)                   | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
+| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `rk`                | Radial kurtosis                                                        | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
+| `rtap`              | Return To Axis Probability                                             | [Scalar](#data-scalar)                       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `rtop`              | Return To Origin Probability                                           | [Scalar](#data-scalar)                       | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
+| `rtpp`              | Return To Plane Probability                                            | [Scalar](#data-scalar)                       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
+| `tort`              | Tortuosity of extra-cellular space                                     | [Scalar](#data-scalar)                       | { `dki` }                                       |                                                                |
+
+While not explicitly included in the table above, *any* [scalar](#data-scalar)
+[extrinsic](parameter-extrinsic) parameter can theoretically be combined
+with a separate source of orientation information from the diffusion model
+in order to produce a [directionally-encoded colour](#data-dec),
+[spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
 
 ## Demonstrative examples
 
@@ -455,7 +468,7 @@ of orientation information from the diffusion model in order to produce a
                sub-01_dti.json
    ```
 
-   Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#parameter-vectors))
+   Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
 
    Contents of JSON file:
 
@@ -486,11 +499,11 @@ of orientation information from the diffusion model in order to produce a
                sub-01_csd.json
    ```
 
-   Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#spherical-harmonics))
-   Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
-   Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#spherical-harmonics))
+   Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+   Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+   Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
-   Contents of file "`sub-01_csd.json`" (common to all intrinsic model parameter images):
+   Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#parameter-intrinsic) model parameter images):
 
    ```JSON
    {
@@ -548,12 +561,12 @@ of orientation information from the diffusion model in order to produce a
                sub-01_noddi.json
    ```
 
-   Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#3-vectors))
+   Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#data-3vector))
 
-   Contents of file "`sub-01_noddi.json`" (common to all intrinsic model parameter images):
+   Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#parameter-intrinsic) model parameter images):
 
    ```JSON
    {
@@ -588,11 +601,11 @@ of orientation information from the diffusion model in order to produce a
                sub-01_bs.json
    ```
 
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction)
-   Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#spherical-coordinates), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
+   Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
 
    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two

From 899a676ad733c080c207f942b84360bd576f66f4 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 16 Aug 2019 23:17:38 +1000
Subject: [PATCH 08/65] BEP016: More minor tweaking

- Various small re-wordings.
- Slightly more use of hyperlinks.
- Short introductions to "parameter terminology" and "data representations" sections.
- Be more explicit about normalised vs. non-normalised 3-vectors, so that structure more clusely mimics that of description of spherical coordinate representation.
- Rename hyperlink names to "parameter terminology" section to better separate from later "intrinsic / extrinsic model parameters" sections.
---
 .../05-diffusion-derivatives.md               | 116 +++++++++++-------
 1 file changed, 74 insertions(+), 42 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index b270bc13..db47f2de 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -47,32 +47,39 @@ informative representations of the diffusion process and the underlying
 biological structure. A wide range of such models are available, each of
 which has its own unique requirements with respect to:
 
--  The input parameters required to define / constrain the model;
+-  The [input](#paramdef-input) parameters required in order to
+   define / constrain the model;
 
--  The appropriate data representation in which the resulting
-   parameters estimated of / from the model are stored on the filesystem;
+-  The appropriate [data representations](#data-representations) utilised to
+   store information parameterised [by](#paramdef-intrinsic) or
+   [from](#paramdef-extrinsic) the model onto the filesystem;
 
 -  The requirements for encapsulation and complete representation of
-   derived orientation information, which is a key strength of diffusion
-   MRI but presents unique challenges for correct interpretation.
+   derived [orientation information](#orientation-specification), which is
+   a key strength of diffusion MRI but presents unique challenges for
+   correct interpretation.
 
 ### Parameter terminology
 
-1. <a name="parameter-intrinsic">*Intrinsic*</a> model parameter:
+Throughout this document, the term "parameter" is used to refer to
+multiple distinct sources of information. The distinction between
+these uses is defined thus:
 
-   Item that is the direct result of fitting the diffusion model to the
-   empirical diffusion-weighted data.
+1. <a name="paramdef-input">*Input*</a> model parameter:
+
+   Value or non-numerical setting that influences the conformation
+   of the diffusion model to the empirical diffusion-weighted data.
 
-1. <a name="parameter-input">*Input*</a> model parameter:
+1. <a name="paramdef-intrinsic">*Intrinsic*</a> model parameter:
 
-   Item that influences the conformation of the diffusion model to the
+   Value that is the direct result of fitting the diffusion model to the
    empirical diffusion-weighted data.
 
-1. <a name="parameter-extrinsic">*Extrinsic*</a> model parameter:
+1. <a name="paramdef-extrinsic">*Extrinsic*</a> model parameter:
 
-   Item that can be calculated from prior estimated intrinsic model
-   parameters, without necessitating reference to the empirical
-   diffusion-weighted data.
+   Value that can be calculated directly from previously estimated
+   intrinsic model parameters, without necessitating reference to
+   the empirical diffusion-weighted data.
 
 ### File names
 
@@ -91,19 +98,18 @@ which has its own unique requirements with respect to:
 ```
 
 -  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-   provides basic model information and [input](#parameter-input)
+   provides basic model information and [input](#paramdef-input)
    model parameters.
 
 -  Images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
-   MAY be defined if additional [extrinsic](#parameter-extrinsic)
-   model parameters beyond the compulsory [intrinsic](#parameter-intrinsic)
-   parameters are to be provided.
+   MAY be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
+   model parameters.
 
 -  OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
    may provide only information or parameters relevant to derivation of each
-   relevant [extrinsic](#parameter-extrinsic) model parameter image.
+   relevant [extrinsic](#paramdef-extrinsic) model parameter image.
 
--  If all [intrinsic](#parameter-intrinsic) model parameters are
+-  If all [intrinsic](#paramdef-intrinsic) model parameters are
    contained within a single image file, field "`_parameter-*`" MUST be
    omitted (for intrinsic parameter image only):
 
@@ -117,11 +123,17 @@ which has its own unique requirements with respect to:
 
 ### Data representations
 
+There are multiple techniques by which data that relate to the anisotropic
+nature of either the diffusion process or underlying tissue may be
+arranged and/or encoded into NIfTI image data. A list of known techniques
+is enumerated below, accompanied by requisite information specific to the
+reading / writing of each representation.
+
 1. <a name="data-scalar">*Scalars*</a>:
 
-   Any model parameter image (whether intrinsic or extrinsic) where a
-   solitary value is defined in each 3D image voxel is referred to here as a
-   "scalar" image.
+   Any model parameter image (whether [intrinsic](#paramdef-intrinsic) or
+   [extrinsic](#paramdef-extrinsic)) where a solitary numerical value is
+   defined in each 3D image voxel is referred to here as a "scalar" image.
 
 1. <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
 
@@ -133,8 +145,10 @@ which has its own unique requirements with respect to:
 1. <a name="data-spherical">*Spherical coordinates*</a>:
 
    4D image where data across volumes within each voxel encode one or
-   more discrete orientations using polar angles, optionally exploiting
-   the distance from origin to encode the value of some parameter.
+   more discrete orientations using angles on the 2-sphere, optionally
+   exploiting the distance from origin to encode the value of some parameter.
+
+   This may take one of two forms:
 
    1. Value per direction
 
@@ -142,7 +156,7 @@ which has its own unique requirements with respect to:
       coordinate, using ISO convention for both the order of parameters
       and reference frame for angles:
 
-      1. Distance from origin; value of embedded parameter SHOULD be
+      1. Distance from origin; value of embedded parameter MUST be
          indicated in "`_parameter-*`" filename field;
 
       1. Inclination / polar angle, in radians, relative to the zenith
@@ -173,8 +187,20 @@ which has its own unique requirements with respect to:
    4D image where data across volumes within each voxel encode one or
    more discrete orientations using triplets of axis dot products.
 
-   If not all 3-vectors are of unit norm, parameter encoded as vector
-   norm SHOULD be indicated in "`_parameter-*`" filename field.
+   This representation may be used in one of two ways:
+
+   1. Value per direction
+
+      Each 3-vector, once explicitly normalized, provides a direction
+      on the unit sphere; the *norm* of each 3-vector additionally encodes
+      the magnitude of some mode parameter, the nature of which MUST be
+      indicated in the "`_parameter-*`" filename field.
+
+   2. Directions only
+
+      Each triplet of values encodes an orientation on the unit sphere
+      (i.e. the 3-vector data are normalized); no quantitative value is
+      associated with each triplet.
 
    Number of image volumes is equal to (3x*N*), where *N* is the maximum
    number of discrete orientations in any voxel in the image.
@@ -205,19 +231,25 @@ which has its own unique requirements with respect to:
 
    4D image containing, for every image voxel, data corresponding to some
    set of model parameters, the names and order of which are defined within
-   the [intrinsic](#parameter-intrinsic) model parameters section.
+   the [intrinsic](#paramdef-intrinsic) model parameters section.
 
 ### Orientation specification
 
-| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                                          |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. If True, no constraints are imposed with respect to the domain on the 2-sphere in which orientations may be specified. |
-| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided.                |
-| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                                    |
-| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information.                                                      |
-| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                                    |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                           |
-| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                                              |
+| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                           |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
+| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
+| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
+| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.                |
+| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                     |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                            |
+| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
+
+If `AntipodalSymmetry` is True, then no constraints are imposed with respect
+to the domain on the 2-sphere in which orientations may be specified;
+for instance, 3-vectors { 0.57735, 0.57735, 0.57735 } and
+{ -0.57735, -0.57735, -0.57735 } are both permissible and equivalent to one
+another.
 
 #### Spherical Harmonics bases
 
@@ -315,7 +347,7 @@ the following key/value pairs irrespective of the particular model:
 | Mask             | OPTIONAL. String. Name of image that was used as a binary mask to specify those voxels for which the model was fit.                                                                          |
 | ModelDescription | OPTIONAL. String. Extended information to describe the model.                                                                                                                                |
 | ModelURL         | OPTIONAL. String. URL to the implementation of the specific model utilized.                                                                                                                  |
-| Parameters       | OPTIONAL. Dictionary. *Input* model parameters that are constant across the image (see below).                                                                                               |
+| Parameters       | OPTIONAL. Dictionary. [Input](#paramdef-input) model parameters that are constant across the image (see examples below).                                                                    |
 
 #### Model bootstrapping
 
@@ -451,7 +483,7 @@ Reserved keywords for models built into the specification are as follows:
 | `tort`              | Tortuosity of extra-cellular space                                     | [Scalar](#data-scalar)                       | { `dki` }                                       |                                                                |
 
 While not explicitly included in the table above, *any* [scalar](#data-scalar)
-[extrinsic](parameter-extrinsic) parameter can theoretically be combined
+[extrinsic](paramdef-extrinsic) parameter can theoretically be combined
 with a separate source of orientation information from the diffusion model
 in order to produce a [directionally-encoded colour](#data-dec),
 [spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
@@ -503,7 +535,7 @@ in order to produce a [directionally-encoded colour](#data-dec),
    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
-   Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#parameter-intrinsic) model parameter images):
+   Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
 
    ```JSON
    {
@@ -566,7 +598,7 @@ in order to produce a [directionally-encoded colour](#data-dec),
    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#data-3vector))
 
-   Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#parameter-intrinsic) model parameter images):
+   Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
 
    ```JSON
    {

From 48c24dc1fc391b6c989f7ad5320a69294c9353be Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Sat, 17 Aug 2019 00:37:41 +1000
Subject: [PATCH 09/65] BEP016: Transpose SH volume count tables

---
 .../05-diffusion-derivatives.md               | 22 +++++--------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index db47f2de..d17d3d16 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -284,14 +284,9 @@ another.
 
       *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-      | ***l<sub>max</sub>*** | ***N*** |
-      | --------------------- | ------- |
-      | 0                     | 1       |
-      | 2                     | 6       |
-      | 4                     | 15      |
-      | 6                     | 28      |
-      | 8                     | 45      |
-      | ...                   | etc.    |
+      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+      | --------------------- | --: | --: | --: | --: | --: | :--: |
+      | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
 
    -  Relationship between maximal degree of *zonal* spherical harmonic
       function (spherical harmonics function where all *m* != 0 terms are
@@ -300,14 +295,9 @@ another.
 
       *N* = 1 + (*l<sub>max</sub>* / 2)
 
-      | ***l<sub>max</sub>*** | ***N*** |
-      | --------------------- | ------- |
-      | 0                     | 1       |
-      | 2                     | 2       |
-      | 4                     | 3       |
-      | 6                     | 4       |
-      | 8                     | 5       |
-      | ...                   | etc.    |
+      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+      | --------------------- | --: | --: | --: | --: | --: | :--: |
+      | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
 
 -  `Descoteaux`
 

From c092f48d3c74e2e660174542aedfe66702761cdf Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 19:08:12 +1000
Subject: [PATCH 10/65] BEP016: Provide example for parameter definitions

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index d17d3d16..a39817dd 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -81,6 +81,13 @@ these uses is defined thus:
    intrinsic model parameters, without necessitating reference to
    the empirical diffusion-weighted data.
 
+For example, consider a diffusion tensor model fit: the number of
+iterations in the optimisation algorithm would be an *input* parameter;
+the six unique diffusion tensor coefficients would be the *intrinsic*
+parameters; the Fractional Anisotropy (FA) would be an *extrinsic*
+parameter (as it is calculated from the diffusion tensor coefficients
+rather than the image data).
+
 ### File names
 
 ```Text

From 7fe44f91ef1549783d0f7a4125acbc012ce7d365 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 22:10:55 +1000
Subject: [PATCH 11/65] BEP016: Change to single-file diffusion models

Based on suggestion in #5. If all model intrinsic parameters are incorporated into a single file, rather than dropping the "_parameter-<param>" field, instead enforce that parameter name "all" be used.
---
 src/05-derivatives/05-diffusion-derivatives.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index a39817dd..ec45ded8 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -117,15 +117,15 @@ rather than the image data).
    relevant [extrinsic](#paramdef-extrinsic) model parameter image.
 
 -  If all [intrinsic](#paramdef-intrinsic) model parameters are
-   contained within a single image file, field "`_parameter-*`" MUST be
-   omitted (for intrinsic parameter image only):
+   contained within a single image file, field "`_parameter-`" MUST nevertheless
+   be included, with value "`all`":
 
    ```Text
    <pipeline_name>/
        sub-<participant_label>/
            dwi/
-               <source_keywords>[_space-<space>][_desc-<label>]_<model>.nii[.gz]
-               <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+               <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
+               <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.json
    ```
 
 ### Data representations

From 7eb44cb6b472942ec29939b64a510dfd9349949d Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 22:12:03 +1000
Subject: [PATCH 12/65] BEP016: Initial explanation of filename

When introducing the file naming convention, give an example of the "_<model>" field.
---
 src/05-derivatives/05-diffusion-derivatives.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ec45ded8..e2bef51a 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -104,6 +104,11 @@ rather than the image data).
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
 ```
 
+-  Field "`<model>`" is a unique identifier corresponding to the particular
+   diffusion model. If the particular diffusion model is one that is included
+   in this specification, then the [prescribed model label](intrinsic-model-parameters)
+   MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
+
 -  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
    provides basic model information and [input](#paramdef-input)
    model parameters.

From 4bc2b9532c957373e30867b7594f15507c8ffff8 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 22:25:57 +1000
Subject: [PATCH 13/65] BEP016: File naming clarification

Re-arranged descriptions of intrinsic and extrinsic model parameters within the file naming section, and corrected a discordance in one dot point that was using an intrinsic model parameter filename path but discussing extrinsic model parameters.
---
 .../05-diffusion-derivatives.md               | 35 ++++++++++---------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index e2bef51a..c9d10b28 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -109,30 +109,33 @@ rather than the image data).
    in this specification, then the [prescribed model label](intrinsic-model-parameters)
    MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
 
--  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-   provides basic model information and [input](#paramdef-input)
-   model parameters.
-
--  Images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
-   MAY be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
-   model parameters.
-
--  OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
-   may provide only information or parameters relevant to derivation of each
-   relevant [extrinsic](#paramdef-extrinsic) model parameter image.
-
--  If all [intrinsic](#paramdef-intrinsic) model parameters are
-   contained within a single image file, field "`_parameter-`" MUST nevertheless
-   be included, with value "`all`":
+-  Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
+   provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
+   of the model. In cases where [intrinsic](#paramdef-intrinsic) model parameters are all
+   contained within a single image file, field "`_parameter-`" nevertheless MUST be
+   included, with value "`all`"; e.g.:
 
    ```Text
    <pipeline_name>/
        sub-<participant_label>/
            dwi/
                <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
-               <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.json
+               <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
    ```
 
+-  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
+   provides basic model information and [input](#paramdef-input)
+   model parameters.
+
+-  OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.nii[.gz]`"
+   may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
+   model parameters.
+
+-  OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+   may be defined to provide only information or parameters relevant to
+   derivation of each relevant [extrinsic](#paramdef-extrinsic) model
+   parameter image.
+
 ### Data representations
 
 There are multiple techniques by which data that relate to the anisotropic

From f07489dc70d07b50f79194c2eea3ef8e5215cb2d Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 22:30:30 +1000
Subject: [PATCH 14/65] BEP016: Spelling fix

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index c9d10b28..1d7d70aa 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -208,7 +208,7 @@ reading / writing of each representation.
 
       Each 3-vector, once explicitly normalized, provides a direction
       on the unit sphere; the *norm* of each 3-vector additionally encodes
-      the magnitude of some mode parameter, the nature of which MUST be
+      the magnitude of some model parameter, the nature of which MUST be
       indicated in the "`_parameter-*`" filename field.
 
    2. Directions only

From 5d14ffad375664cc1c5b6be5382d23c512837391 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 11 Sep 2019 22:37:10 +1000
Subject: [PATCH 15/65] BEP016: Fix missing anchor links

---
 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 1d7d70aa..07509974 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -331,9 +331,9 @@ ideally be integrated in a future version of the specification.
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors] image with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                              |
+| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors](#data-param) image with parameter name "`all`" with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                              |
 | `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#data-pdf)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors] image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#data-param) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One [scalar](#data-scalar) image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

From a804aeb408ef8cabb8b0dcaee14cfe1ef5c322df Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 18 Sep 2019 18:45:41 +1000
Subject: [PATCH 16/65] BEP016: Move orientation specification

Provide information on specification of orientation data after the various models and model parameters have been explained.
---
 .../05-diffusion-derivatives.md               | 152 +++++++++---------
 1 file changed, 79 insertions(+), 73 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 07509974..a963967e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -144,6 +144,10 @@ arranged and/or encoded into NIfTI image data. A list of known techniques
 is enumerated below, accompanied by requisite information specific to the
 reading / writing of each representation.
 
+For data that encode orientation information, there are fields that MUST
+be specified in the sidecar JSON file in order to ensure appropriate
+interpretation of that information; see [orientation specification](#orientation-specification)).
+
 1. <a name="data-scalar">*Scalars*</a>:
 
    Any model parameter image (whether [intrinsic](#paramdef-intrinsic) or
@@ -227,7 +231,8 @@ reading / writing of each representation.
    spherical harmonics basis.
 
    Number of image volumes depends on the spherical harmonic basis employed,
-   and the maximal spherical harmonic degree *l<sub>max</sub>*.
+   and the maximal spherical harmonic degree *l<sub>max</sub>* (see
+   [spherical harmonics bases](#spherical-harmonics-bases)).
 
 1. <a name="data-amp">*Amplitudes*</a>:
 
@@ -235,8 +240,9 @@ reading / writing of each representation.
    amplitudes of a discrete function spanning the 2-sphere.
 
    Number of image volumes corresponds to the number of discrete directions
-   on the unit sphere along which samples for the function in each voxel
-   are provided.
+   on the unit sphere along which samples for the spherical function in
+   each voxel are provided; these directions MUST themselves be provided
+   in the associated sidecar JSON file (see [orientation specification](#orientation-specification)).
 
 1. <a name="data-pdf">*Probability Distribution Functions (PDFs)*</a>:
 
@@ -248,76 +254,6 @@ reading / writing of each representation.
    set of model parameters, the names and order of which are defined within
    the [intrinsic](#paramdef-intrinsic) model parameters section.
 
-### Orientation specification
-
-| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                           |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
-| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
-| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
-| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.                |
-| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference for orientation information.                                                                                     |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                            |
-| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
-
-If `AntipodalSymmetry` is True, then no constraints are imposed with respect
-to the domain on the 2-sphere in which orientations may be specified;
-for instance, 3-vectors { 0.57735, 0.57735, 0.57735 } and
-{ -0.57735, -0.57735, -0.57735 } are both permissible and equivalent to one
-another.
-
-#### Spherical Harmonics bases
-
--  `MRtrix3`
-
-   -  Antipodally symmetric: all basis functions with odd degree are
-      assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
-
-   -  Functions assumed to be real: conjugate symmetry is assumed, i.e.
-      *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
-      conjugate.
-
-   -  Mapping of image volumes to spherical harmonic basis function
-      coefficients:
-
-      | **Volume** | **Coefficient**                   |
-      | ---------- | --------------------------------- |
-      | 0          | *l* = 0, *m* = 0                  |
-      | 1          | *l* = 2, *m* = 2 (imaginary part) |
-      | 2          | *l* = 2, *m* = 1 (imaginary part) |
-      | 3          | *l* = 2, *m* = 0                  |
-      | 4          | *l* = 2, *m* = 1 (real part)      |
-      | 5          | *l* = 2, *m* = 2 (real part)      |
-      | 6          | *l* = 4, *m* = 4 (imaginary part) |
-      | 7          | *l* = 4, *m* = 3 (imaginary part) |
-      | ...        | etc.                              |
-
-   -  Normalisation: ***TODO***
-
-   -  Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
-      and number of image volumes *N*:
-
-      *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
-
-      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
-      | --------------------- | --: | --: | --: | --: | --: | :--: |
-      | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
-
-   -  Relationship between maximal degree of *zonal* spherical harmonic
-      function (spherical harmonics function where all *m* != 0 terms are
-      assumed to be zero; used for e.g. response function definition) and
-      number of coefficients *N*:
-
-      *N* = 1 + (*l<sub>max</sub>* / 2)
-
-      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
-      | --------------------- | --: | --: | --: | --: | --: | :--: |
-      | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
-
--  `Descoteaux`
-
-   ***TODO***
-
 ### Intrinsic model parameters
 
 The following models are codified within the specification, and the model
@@ -493,6 +429,76 @@ with a separate source of orientation information from the diffusion model
 in order to produce a [directionally-encoded colour](#data-dec),
 [spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
 
+### Orientation specification
+
+| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                           |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
+| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
+| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
+| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `pdf`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.         |
+| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                            |
+| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
+
+If `AntipodalSymmetry` is True, then no constraints are imposed with respect
+to the domain on the 2-sphere in which orientations may be specified;
+for instance, 3-vectors { 0.57735, 0.57735, 0.57735 } and
+{ -0.57735, -0.57735, -0.57735 } are both permissible and equivalent to one
+another.
+
+#### Spherical Harmonics bases
+
+-  `MRtrix3`
+
+   -  Antipodally symmetric: all basis functions with odd degree are
+      assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
+
+   -  Functions assumed to be real: conjugate symmetry is assumed, i.e.
+      *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
+      conjugate.
+
+   -  Mapping of image volumes to spherical harmonic basis function
+      coefficients:
+
+      | **Volume** | **Coefficient**                   |
+      | ---------- | --------------------------------- |
+      | 0          | *l* = 0, *m* = 0                  |
+      | 1          | *l* = 2, *m* = 2 (imaginary part) |
+      | 2          | *l* = 2, *m* = 1 (imaginary part) |
+      | 3          | *l* = 2, *m* = 0                  |
+      | 4          | *l* = 2, *m* = 1 (real part)      |
+      | 5          | *l* = 2, *m* = 2 (real part)      |
+      | 6          | *l* = 4, *m* = 4 (imaginary part) |
+      | 7          | *l* = 4, *m* = 3 (imaginary part) |
+      | ...        | etc.                              |
+
+   -  Normalisation: ***TODO***
+
+   -  Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+      and number of image volumes *N*:
+
+      *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+
+      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+      | --------------------- | --: | --: | --: | --: | --: | :--: |
+      | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
+
+   -  Relationship between maximal degree of *zonal* spherical harmonic
+      function (spherical harmonics function where all *m* != 0 terms are
+      assumed to be zero; used for e.g. response function definition) and
+      number of coefficients *N*:
+
+      *N* = 1 + (*l<sub>max</sub>* / 2)
+
+      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+      | --------------------- | --: | --: | --: | --: | --: | :--: |
+      | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
+
+-  `Descoteaux`
+
+   ***TODO***
+
 ## Demonstrative examples
 
 -  A basic Diffusion Tensor fit:

From 7227a75450f23bf6e6ef93b30cf991625b3a50ea Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 13:52:13 +1100
Subject: [PATCH 17/65] BEP016: Revise SH description

Revised based on MRtrix3/mrtrix3#1635.
Manual merge / cherry-pick of: c6539851, 8b278282, c6539851, ebbf0d3d, d7b4731d, 99e92e0a, 6bfc7849 due to unresolvable conflict in bids-standard/bids-bep016#8.
---
 .../05-diffusion-derivatives.md               | 56 ++++++++++++-------
 1 file changed, 37 insertions(+), 19 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index a963967e..8b16d91c 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -447,33 +447,51 @@ for instance, 3-vectors { 0.57735, 0.57735, 0.57735 } and
 { -0.57735, -0.57735, -0.57735 } are both permissible and equivalent to one
 another.
 
-#### Spherical Harmonics bases
+#### Spherical Harmonics
 
--  `MRtrix3`
+- Concepts shared across all spherical harmonics bases:
 
-   -  Antipodally symmetric: all basis functions with odd degree are
-      assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
+   -  Basis functions:
+
+      ![SH basis functions](https://latex.codecogs.com/gif.latex?Y_l^m(\theta,\phi)&space;=&space;\sqrt{\frac{(2l&plus;1)}{4\pi}\frac{(l-m)!}{(l&plus;m)!}}&space;P_l^m(\cos&space;\theta)&space;e^{im\phi}")
+
+      for integer *order* *l*, *phase* *m*, associated Legendre polynomials *P*.
+
+   -  (Truncated) basis coefficients:
+
+      ![SH basis coefficients](https://latex.codecogs.com/gif.latex?f(\theta,\phi)&space;=&space;\sum_{l=0}^{l_\text{max}}&space;\sum_{m=-l}^{l}&space;c_l^m&space;Y_l^m(\theta,\phi)")
+
+      for *maximum* spherical harmonic order *l<sub>max</sub>*.
+
+-  `MRtrix3`
 
    -  Functions assumed to be real: conjugate symmetry is assumed, i.e.
       *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
       conjugate.
 
-   -  Mapping of image volumes to spherical harmonic basis function
-      coefficients:
+   -  Antipodally symmetric: all basis functions with odd degree are
+      assumed zero; `AntipodalSymmetry` MUST NOT be set to `True`.
+
+   -  Utilised basis functions:
+
+      ![MRtrix3 SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
+
+   -  Mapping between image volume *V<sub>lm</sub>* and spherical harmonic basis
+      function coefficient *c<sub>lm</sub>*:
 
-      | **Volume** | **Coefficient**                   |
-      | ---------- | --------------------------------- |
-      | 0          | *l* = 0, *m* = 0                  |
-      | 1          | *l* = 2, *m* = 2 (imaginary part) |
-      | 2          | *l* = 2, *m* = 1 (imaginary part) |
-      | 3          | *l* = 2, *m* = 0                  |
-      | 4          | *l* = 2, *m* = 1 (real part)      |
-      | 5          | *l* = 2, *m* = 2 (real part)      |
-      | 6          | *l* = 4, *m* = 4 (imaginary part) |
-      | 7          | *l* = 4, *m* = 3 (imaginary part) |
-      | ...        | etc.                              |
+      *V<sub>lm</sub>* = (*l*(*l*+1) / 2) + *m*
 
-   -  Normalisation: ***TODO***
+      | ***V<sub>lm</sub>*** | ***c<sub>lm</sub>***              |
+      | -------------------- | --------------------------------- |
+      | 0                    | *l* = 0, *m* = 0                  |
+      | 1                    | *l* = 2, *m* = 2 (imaginary part) |
+      | 2                    | *l* = 2, *m* = 1 (imaginary part) |
+      | 3                    | *l* = 2, *m* = 0                  |
+      | 4                    | *l* = 2, *m* = 1 (real part)      |
+      | 5                    | *l* = 2, *m* = 2 (real part)      |
+      | 6                    | *l* = 4, *m* = 4 (imaginary part) |
+      | 7                    | *l* = 4, *m* = 3 (imaginary part) |
+      | ...                  | etc.                              |
 
    -  Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
       and number of image volumes *N*:
@@ -493,7 +511,7 @@ another.
 
       | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
       | --------------------- | --: | --: | --: | --: | --: | :--: |
-      | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
+      | ***N***               |  1  |  2  |  3  |  4  |  5  | etc. |
 
 -  `Descoteaux`
 

From 3c412f6bdab33ad6acce8246c9e9b35805076cec Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:12:12 +1100
Subject: [PATCH 18/65] BEP016: Initial conformity to markdown formatting

---
 .../05-diffusion-derivatives.md               | 868 +++++++++---------
 1 file changed, 456 insertions(+), 412 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index a963967e..281c7e70 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -47,17 +47,17 @@ informative representations of the diffusion process and the underlying
 biological structure. A wide range of such models are available, each of
 which has its own unique requirements with respect to:
 
--  The [input](#paramdef-input) parameters required in order to
-   define / constrain the model;
+-   The [input](#paramdef-input) parameters required in order to
+    define / constrain the model;
 
--  The appropriate [data representations](#data-representations) utilised to
-   store information parameterised [by](#paramdef-intrinsic) or
-   [from](#paramdef-extrinsic) the model onto the filesystem;
+-   The appropriate [data representations](#data-representations) utilised to
+    store information parameterised [by](#paramdef-intrinsic) or
+    [from](#paramdef-extrinsic) the model onto the filesystem;
 
--  The requirements for encapsulation and complete representation of
-   derived [orientation information](#orientation-specification), which is
-   a key strength of diffusion MRI but presents unique challenges for
-   correct interpretation.
+-   The requirements for encapsulation and complete representation of
+    derived [orientation information](#orientation-specification), which is
+    a key strength of diffusion MRI but presents unique challenges for
+    correct interpretation.
 
 ### Parameter terminology
 
@@ -65,21 +65,21 @@ Throughout this document, the term "parameter" is used to refer to
 multiple distinct sources of information. The distinction between
 these uses is defined thus:
 
-1. <a name="paramdef-input">*Input*</a> model parameter:
+1.  <a name="paramdef-input">*Input*</a> model parameter:
 
-   Value or non-numerical setting that influences the conformation
-   of the diffusion model to the empirical diffusion-weighted data.
+    Value or non-numerical setting that influences the conformation
+    of the diffusion model to the empirical diffusion-weighted data.
 
-1. <a name="paramdef-intrinsic">*Intrinsic*</a> model parameter:
+1.  <a name="paramdef-intrinsic">*Intrinsic*</a> model parameter:
 
-   Value that is the direct result of fitting the diffusion model to the
-   empirical diffusion-weighted data.
+    Value that is the direct result of fitting the diffusion model to the
+    empirical diffusion-weighted data.
 
-1. <a name="paramdef-extrinsic">*Extrinsic*</a> model parameter:
+1.  <a name="paramdef-extrinsic">*Extrinsic*</a> model parameter:
 
-   Value that can be calculated directly from previously estimated
-   intrinsic model parameters, without necessitating reference to
-   the empirical diffusion-weighted data.
+    Value that can be calculated directly from previously estimated
+    intrinsic model parameters, without necessitating reference to
+    the empirical diffusion-weighted data.
 
 For example, consider a diffusion tensor model fit: the number of
 iterations in the optimisation algorithm would be an *input* parameter;
@@ -104,37 +104,37 @@ rather than the image data).
             [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
 ```
 
--  Field "`<model>`" is a unique identifier corresponding to the particular
-   diffusion model. If the particular diffusion model is one that is included
-   in this specification, then the [prescribed model label](intrinsic-model-parameters)
-   MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
-
--  Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
-   provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
-   of the model. In cases where [intrinsic](#paramdef-intrinsic) model parameters are all
-   contained within a single image file, field "`_parameter-`" nevertheless MUST be
-   included, with value "`all`"; e.g.:
-
-   ```Text
-   <pipeline_name>/
-       sub-<participant_label>/
-           dwi/
-               <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
-               <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
-   ```
-
--  File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-   provides basic model information and [input](#paramdef-input)
-   model parameters.
-
--  OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.nii[.gz]`"
-   may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
-   model parameters.
-
--  OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
-   may be defined to provide only information or parameters relevant to
-   derivation of each relevant [extrinsic](#paramdef-extrinsic) model
-   parameter image.
+-   Field "`<model>`" is a unique identifier corresponding to the particular
+    diffusion model. If the particular diffusion model is one that is included
+    in this specification, then the [prescribed model label](intrinsic-model-parameters)
+    MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
+
+-   Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
+    provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
+    of the model. In cases where [intrinsic](#paramdef-intrinsic) model parameters are all
+    contained within a single image file, field "`_parameter-`" nevertheless MUST be
+    included, with value "`all`"; e.g.:
+
+    ```Text
+    <pipeline_name>/
+        sub-<participant_label>/
+            dwi/
+                <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
+                <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+    ```
+
+-   File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
+    provides basic model information and [input](#paramdef-input)
+    model parameters.
+
+-   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.nii[.gz]`"
+    may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
+    model parameters.
+
+-   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+    may be defined to provide only information or parameters relevant to
+    derivation of each relevant [extrinsic](#paramdef-extrinsic) model
+    parameter image.
 
 ### Data representations
 
@@ -148,111 +148,111 @@ For data that encode orientation information, there are fields that MUST
 be specified in the sidecar JSON file in order to ensure appropriate
 interpretation of that information; see [orientation specification](#orientation-specification)).
 
-1. <a name="data-scalar">*Scalars*</a>:
+1.  <a name="data-scalar">*Scalars*</a>:
 
-   Any model parameter image (whether [intrinsic](#paramdef-intrinsic) or
-   [extrinsic](#paramdef-extrinsic)) where a solitary numerical value is
-   defined in each 3D image voxel is referred to here as a "scalar" image.
+    Any model parameter image (whether [intrinsic](#paramdef-intrinsic) or
+    [extrinsic](#paramdef-extrinsic)) where a solitary numerical value is
+    defined in each 3D image voxel is referred to here as a "scalar" image.
 
-1. <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
+1.  <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
 
-   4D image with three volumes, intended to be interpreted as red, green
-   and blue colour intensities for visualisation
-   \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
-   values.
+    4D image with three volumes, intended to be interpreted as red, green
+    and blue colour intensities for visualisation
+    \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
+    values.
 
-1. <a name="data-spherical">*Spherical coordinates*</a>:
+1.  <a name="data-spherical">*Spherical coordinates*</a>:
 
-   4D image where data across volumes within each voxel encode one or
-   more discrete orientations using angles on the 2-sphere, optionally
-   exploiting the distance from origin to encode the value of some parameter.
+    4D image where data across volumes within each voxel encode one or
+    more discrete orientations using angles on the 2-sphere, optionally
+    exploiting the distance from origin to encode the value of some parameter.
 
-   This may take one of two forms:
+    This may take one of two forms:
 
-   1. Value per direction
+    1.  Value per direction
 
-      Each consecutive triplet of image volumes encodes a spherical
-      coordinate, using ISO convention for both the order of parameters
-      and reference frame for angles:
+        Each consecutive triplet of image volumes encodes a spherical
+        coordinate, using ISO convention for both the order of parameters
+        and reference frame for angles:
 
-      1. Distance from origin; value of embedded parameter MUST be
-         indicated in "`_parameter-*`" filename field;
+        1.  Distance from origin; value of embedded parameter MUST be
+            indicated in "`_parameter-*`" filename field;
 
-      1. Inclination / polar angle, in radians, relative to the zenith
-         direction being the positive direction of the *third* reference
-         axis (see [orientation specification](#orientation-specification));
+        1.  Inclination / polar angle, in radians, relative to the zenith
+            direction being the positive direction of the *third* reference
+            axis (see [orientation specification](#orientation-specification));
 
-      1. Azimuth angle, in radians, orthogonal to the zenith direction,
-         with value of 0.0 corresponding to the *first* reference axis
-         (see [orientation specification](#orientation-specification)),
-         increasing according to the right-hand rule about the zenith
-         direction.
+        1.  Azimuth angle, in radians, orthogonal to the zenith direction,
+            with value of 0.0 corresponding to the *first* reference axis
+            (see [orientation specification](#orientation-specification)),
+            increasing according to the right-hand rule about the zenith
+            direction.
 
-      Number of image volumes is equal to (3x*N*), where *N* is the maximum
-      number of discrete orientations in any voxel in the image.
+        Number of image volumes is equal to (3x*N*), where *N* is the maximum
+        number of discrete orientations in any voxel in the image.
 
-   1. Directions only
+    1.  Directions only
 
-      Each consecutive pair of image volumes encodes inclination /
-      azimuth pairs, with order & convention identical to that above
-      (equivalent to spherical coordinate with assumed unity distance from
-      origin).
+        Each consecutive pair of image volumes encodes inclination /
+        azimuth pairs, with order & convention identical to that above
+        (equivalent to spherical coordinate with assumed unity distance from
+        origin).
 
-      Number of image volumes is equal to (2x*N*), where *N* is the maximum
-      number of discrete orientations in any voxel in the image.
+        Number of image volumes is equal to (2x*N*), where *N* is the maximum
+        number of discrete orientations in any voxel in the image.
 
-1. <a name="data-3vector">*3-Vectors*</a>:
+1.  <a name="data-3vector">*3-Vectors*</a>:
 
-   4D image where data across volumes within each voxel encode one or
-   more discrete orientations using triplets of axis dot products.
+    4D image where data across volumes within each voxel encode one or
+    more discrete orientations using triplets of axis dot products.
 
-   This representation may be used in one of two ways:
+    This representation may be used in one of two ways:
 
-   1. Value per direction
+    1.  Value per direction
 
-      Each 3-vector, once explicitly normalized, provides a direction
-      on the unit sphere; the *norm* of each 3-vector additionally encodes
-      the magnitude of some model parameter, the nature of which MUST be
-      indicated in the "`_parameter-*`" filename field.
+        Each 3-vector, once explicitly normalized, provides a direction
+        on the unit sphere; the *norm* of each 3-vector additionally encodes
+        the magnitude of some model parameter, the nature of which MUST be
+        indicated in the "`_parameter-*`" filename field.
 
-   2. Directions only
+    1.  Directions only
 
-      Each triplet of values encodes an orientation on the unit sphere
-      (i.e. the 3-vector data are normalized); no quantitative value is
-      associated with each triplet.
+        Each triplet of values encodes an orientation on the unit sphere
+        (i.e. the 3-vector data are normalized); no quantitative value is
+        associated with each triplet.
 
-   Number of image volumes is equal to (3x*N*), where *N* is the maximum
-   number of discrete orientations in any voxel in the image.
+    Number of image volumes is equal to (3x*N*), where *N* is the maximum
+    number of discrete orientations in any voxel in the image.
 
-1. <a name="data-sh">*Spherical Harmonics (SH)*</a>:
+1.  <a name="data-sh">*Spherical Harmonics (SH)*</a>:
 
-   4D image where data across volumes within each voxel represent a
-   continuous function spanning the 2-sphere as coefficient values using a
-   spherical harmonics basis.
+    4D image where data across volumes within each voxel represent a
+    continuous function spanning the 2-sphere as coefficient values using a
+    spherical harmonics basis.
 
-   Number of image volumes depends on the spherical harmonic basis employed,
-   and the maximal spherical harmonic degree *l<sub>max</sub>* (see
-   [spherical harmonics bases](#spherical-harmonics-bases)).
+    Number of image volumes depends on the spherical harmonic basis employed,
+    and the maximal spherical harmonic degree *l<sub>max</sub>* (see
+    [spherical harmonics bases](#spherical-harmonics-bases)).
 
-1. <a name="data-amp">*Amplitudes*</a>:
+1.  <a name="data-amp">*Amplitudes*</a>:
 
-   4D image where data across volumes within each voxel represent
-   amplitudes of a discrete function spanning the 2-sphere.
+    4D image where data across volumes within each voxel represent
+    amplitudes of a discrete function spanning the 2-sphere.
 
-   Number of image volumes corresponds to the number of discrete directions
-   on the unit sphere along which samples for the spherical function in
-   each voxel are provided; these directions MUST themselves be provided
-   in the associated sidecar JSON file (see [orientation specification](#orientation-specification)).
+    Number of image volumes corresponds to the number of discrete directions
+    on the unit sphere along which samples for the spherical function in
+    each voxel are provided; these directions MUST themselves be provided
+    in the associated sidecar JSON file (see [orientation specification](#orientation-specification)).
 
-1. <a name="data-pdf">*Probability Distribution Functions (PDFs)*</a>:
+1.  <a name="data-pdf">*Probability Distribution Functions (PDFs)*</a>:
 
-   ***TODO***
+    ***TODO***
 
-1. <a name="data-param">*Parameter vectors*</a>:
+1.  <a name="data-param">*Parameter vectors*</a>:
 
-   4D image containing, for every image voxel, data corresponding to some
-   set of model parameters, the names and order of which are defined within
-   the [intrinsic](#paramdef-intrinsic) model parameters section.
+    4D image containing, for every image voxel, data corresponding to some
+    set of model parameters, the names and order of which are defined within
+    the [intrinsic](#paramdef-intrinsic) model parameters section.
 
 ### Intrinsic model parameters
 
@@ -316,85 +316,129 @@ field depends on the particular model used.
 
 Reserved keywords for models built into the specification are as follows:
 
--  `bs` :
-
-   -  `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
-   -  `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
-   -  `ModelBall`: String. Model used to describe the "ball" component in the model.
-   -  `ModelSticks`: String. Model used to describe the "stick" component in the model.
-
--  `csa` :
-
-   -  `SphericalHarmonicOrder` : value
-   -  `Smoothing` : value
-   -  `Basis` : value
-
--  `csd`:
-
-   -  `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
-   -  `ResponseFunctionZSH`: Two options:
-      -  Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
-      -  Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
-   -  `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-   -  `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
-   -  `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
-   -  `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
-
--  `dsi` :
-
-   -  `GridSize` : value
-   -  `RStart` : value
-   -  `RStep` : value
-   -  `REnd` : value
-   -  `FilterWidth` : value
-
--  `dti` :
-
-   -  `RESTORESigma`: Float
-
--  `forecast` :
-
-   -  `Sphere` : value
-   -  `DecAlg` : value
-   -  `LambdaLb` : value
-   -  `SphericalHarmonicsOrder` : value
-
--  `mapmri` :
-
-   -  `RadialOrder` : value
-   -  `LaplacianRegularization` : bool
-   -  `LaplacianWeighting` : value
-   -  `PositivityConstraint` : bool
-   -  `Tau` : value
-   -  `ConstrainE0` : value
-   -  `PositiveConstraint` : value
-   -  `PosGrid` : value
-   -  `PosRadius` : value
-   -  `AnisotropicScaling` : bool
-   -  `EigenvalueThreshold` : value
-   -  `PosGrid` : value
-   -  `BvalThreshold` : value
-   -  `DTIScaleEstimation` : bool
-   -  `StaticDiffusivity` : value
-
--  `noddi`:
-
-   -  `DPar` : value
-   -  `DIso` : value
-   -  `Lambda1` : value
-   -  `Lambda2` : value
+-   `bs` :
+
+    -   `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
+    
+    -   `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
+    
+    -   `ModelBall`: String. Model used to describe the "ball" component in the model.
+    
+    -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
+
+-   `csa` :
+
+    -   `SphericalHarmonicOrder` : value
+    
+    -   `Smoothing` : value
+    
+    -   `Basis` : value
+
+-   `csd`:
+
+    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
+    
+    -   `ResponseFunctionZSH`: Two options:
+    
+        -   Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
+        
+        -   Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
+        
+    -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
+    
+    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+    
+    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
+    
+    -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
+
+-   `dsi` :
+
+    -   `GridSize` : value
+    
+    -   `RStart` : value
+    
+    -   `RStep` : value
+    
+    -   `REnd` : value
+    
+    -   `FilterWidth` : value
+
+-   `dti` :
+
+    -   `RESTORESigma`: Float
+
+-   `forecast` :
+
+    -   `Sphere` : value
+    
+    -   `DecAlg` : value
+    
+    -   `LambdaLb` : value
+    
+    -   `SphericalHarmonicsOrder` : value
+
+-   `mapmri` :
+
+    -   `RadialOrder` : value
+    
+    -   `LaplacianRegularization` : bool
+    
+    -   `LaplacianWeighting` : value
+    
+    -   `PositivityConstraint` : bool
+    
+    -   `Tau` : value
+    
+    -   `ConstrainE0` : value
+    
+    -   `PositiveConstraint` : value
+    
+    -   `PosGrid` : value
+    
+    -   `PosRadius` : value
+    
+    -   `AnisotropicScaling` : bool
+    
+    -   `EigenvalueThreshold` : value
+    
+    -   `PosGrid` : value
+    
+    -   `BvalThreshold` : value
+    
+    -   `DTIScaleEstimation` : bool
+    
+    -   `StaticDiffusivity` : value
+
+-   `noddi`:
+
+    -   `DPar` : value
+    
+    -   `DIso` : value
+    
+    -   `Lambda1` : value
+    
+    -   `Lambda2` : value
 
 -  `shore` :
 
-   -  `RadialOrder` : value
-   -  `Zeta` : value
-   -  `LambdaN` : value
-   -  `LambdaL` : value
-   -  `Tau` : value
-   -  `ConstrainE0` : value
-   -  `PositiveConstraint` : value
-   -  `PosGrid` : value
-   -  `PosRadius` : value
+    -   `RadialOrder` : value
+    
+    -   `Zeta` : value
+    
+    -   `LambdaN` : value
+    
+    -   `LambdaL` : value
+    
+    -   `Tau` : value
+    
+    -   `ConstrainE0` : value
+    
+    -   `PositiveConstraint` : value
+    
+    -   `PosGrid` : value
+    
+    -   `PosRadius` : value
 
 ### Extrinsic model parameters
 
@@ -449,236 +493,236 @@ another.
 
 #### Spherical Harmonics bases
 
--  `MRtrix3`
+-   `MRtrix3`
 
-   -  Antipodally symmetric: all basis functions with odd degree are
-      assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
+    -   Antipodally symmetric: all basis functions with odd degree are
+        assumed zero; `AntipodalSymmetry` MUST NOT be set to True.
 
-   -  Functions assumed to be real: conjugate symmetry is assumed, i.e.
-      *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
-      conjugate.
+    -   Functions assumed to be real: conjugate symmetry is assumed, i.e.
+        *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
+        conjugate.
 
-   -  Mapping of image volumes to spherical harmonic basis function
-      coefficients:
+    -   Mapping of image volumes to spherical harmonic basis function
+        coefficients:
 
-      | **Volume** | **Coefficient**                   |
-      | ---------- | --------------------------------- |
-      | 0          | *l* = 0, *m* = 0                  |
-      | 1          | *l* = 2, *m* = 2 (imaginary part) |
-      | 2          | *l* = 2, *m* = 1 (imaginary part) |
-      | 3          | *l* = 2, *m* = 0                  |
-      | 4          | *l* = 2, *m* = 1 (real part)      |
-      | 5          | *l* = 2, *m* = 2 (real part)      |
-      | 6          | *l* = 4, *m* = 4 (imaginary part) |
-      | 7          | *l* = 4, *m* = 3 (imaginary part) |
-      | ...        | etc.                              |
+        | **Volume** | **Coefficient**                   |
+        | ---------- | --------------------------------- |
+        | 0          | *l* = 0, *m* = 0                  |
+        | 1          | *l* = 2, *m* = 2 (imaginary part) |
+        | 2          | *l* = 2, *m* = 1 (imaginary part) |
+        | 3          | *l* = 2, *m* = 0                  |
+        | 4          | *l* = 2, *m* = 1 (real part)      |
+        | 5          | *l* = 2, *m* = 2 (real part)      |
+        | 6          | *l* = 4, *m* = 4 (imaginary part) |
+        | 7          | *l* = 4, *m* = 3 (imaginary part) |
+        | ...        | etc.                              |
 
-   -  Normalisation: ***TODO***
+    -   Normalisation: ***TODO***
 
-   -  Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
-      and number of image volumes *N*:
+    -   Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+        and number of image volumes *N*:
 
-      *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+        *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
-      | --------------------- | --: | --: | --: | --: | --: | :--: |
-      | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
+        | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+        | --------------------- | --: | --: | --: | --: | --: | :--: |
+        | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
 
-   -  Relationship between maximal degree of *zonal* spherical harmonic
-      function (spherical harmonics function where all *m* != 0 terms are
-      assumed to be zero; used for e.g. response function definition) and
-      number of coefficients *N*:
+    -   Relationship between maximal degree of *zonal* spherical harmonic
+        function (spherical harmonics function where all *m* != 0 terms are
+        assumed to be zero; used for e.g. response function definition) and
+        number of coefficients *N*:
 
-      *N* = 1 + (*l<sub>max</sub>* / 2)
+        *N* = 1 + (*l<sub>max</sub>* / 2)
 
-      | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
-      | --------------------- | --: | --: | --: | --: | --: | :--: |
-      | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
+        | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+        | --------------------- | --: | --: | --: | --: | --: | :--: |
+        | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
 
--  `Descoteaux`
+-   `Descoteaux`
 
-   ***TODO***
+    ***TODO***
 
 ## Demonstrative examples
 
--  A basic Diffusion Tensor fit:
-
-   ```Text
-   my_diffusion_pipeline/
-       sub-01/
-           dwi/
-               sub-01_dti.nii.gz
-               sub-01_dti.json
-   ```
-
-   Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
-
-   Contents of JSON file:
-
-   ```JSON
-   {
-       "Model": "Diffusion Tensor",
-       "OrientationRepresentation": "param",
-       "ReferenceAxes": "xyz",
-       "Parameters": {
-           "FitMethod": "ols",
-           "OutlierRejection": False
-       }
-   }
-   ```
-
--  A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
-
-   ```Text
-   my_diffusion_pipeline/
-       sub-01/
-           dwi/
-               sub-01_desc-wm_csd.nii.gz
-               sub-01_desc-wm_csd.json
-               sub-01_desc-gm_csd.nii.gz
-               sub-01_desc-gm_csd.json
-               sub-01_desc-csf_csd.nii.gz
-               sub-01_desc-csf_csd.json
-               sub-01_csd.json
-   ```
-
-   Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-   Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-   Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-
-   Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
-
-   ```JSON
-   {
-       "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-       "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
-       "Shells": [ 0, 1000, 2000, 3000 ],
-       "Parameters": {
-           "SphericalHarmonicBasis": "MRtrix3",
-           "NonNegativityConstraint": "hard"
-       }
-   }
-   ```
-
-   Contents of JSON file "`sub-01_desc-wm_csd.json`":
-
-   ```JSON
-   {
-       "OrientationRepresentation": "sh",
-       "ReferenceAxes": "xyz",
-       "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
-                                [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
-                                [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
-                                [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
-       "SphericalHarmonicDegree": 8,
-       "Tissue": "White matter"
-   }
-   ```
-
-   Contents of JSON file "`sub-01_desc-gm_csd.json`":
-
-   ```JSON
-   {
-       "OrientationRepresentation": "sh",
-       "ReferenceAxes": "xyz",
-       "ResponseFunctionZSH": [ [ 1041.0 ],
-                                [ 436.6 ],
-                                [ 224.9 ],
-                                [ 128.8 ] ],
-       "SphericalHarmonicDegree": 0,
-       "Tissue": "Grey matter"
-   }
-   ```
-
--  A NODDI fit:
-
-   ```Text
-   my_diffusion_pipeline/
-       sub-01/
-           dwi/
-               sub-01_parameter-icvf_noddi.nii.gz
-               sub-01_parameter-isovf_noddi.nii.gz
-               sub-01_parameter-od_noddi.nii.gz
-               sub-01_parameter-direction_noddi.nii.gz
-               sub-01_parameter-direction_noddi.json
-               sub-01_noddi.json
-   ```
-
-   Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#data-3vector))
-
-   Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
-
-   ```JSON
-   {
-       "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
-       "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
-   }
-   ```
-
-   Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
-
-   ```JSON
-   {
-       "OrientationRepresentation": "3vector",
-       "ReferenceAxes": "???"
-   }
-   ```
-
--  An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
-   bootstrap realisations):
-
-   ```Text
-   my_diffusion_pipeline/
-       sub-01/
-           dwi/
-               sub-01_desc-mean_parameter-bzero_bs.nii.gz
-               sub-01_desc-mean_parameter-dmean_bs.nii.gz
-               sub-01_desc-mean_parameter-dstd_bs.nii.gz
-               sub-01_desc-mean_parameter-sticks_bs.nii.gz
-               sub-01_desc-mean_parameter-sticks_bs.json
-               sub-01_desc-merged_parameter-sticks_bs.nii.gz
-               sub-01_desc-merged_parameter-sticks_bs.json
-               sub-01_bs.json
-   ```
-
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-   Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
-   Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
-
-   Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
-   and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
-   files are identical):
-
-   ```JSON
-   {
-       "OrientationRepresentation": "spherical",
-       "ReferenceAxes": "ijk"
-   }
-   ```
-
-   Contents of JSON file "`sub-01_bs.json`":
-
-   ```JSON
-   {
-       "Model": "Ball-And-Sticks model using FSL bedpostx",
-       "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-       "Parameters": {
-           "ARDFudgeFactor": 1.0,
-           "Fibers": 3,
-           "Samples": 50
-       },
-       "BootstrapParameters": {
-           "Burnin": 1000,
-           "Jumps": 1250,
-           "SampleEvery": 25
-       }
-   }
-   ```
+-   A basic Diffusion Tensor fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_dti.nii.gz
+                sub-01_dti.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+
+    Contents of JSON file:
+
+    ```JSON
+    {
+        "Model": "Diffusion Tensor",
+        "OrientationRepresentation": "param",
+        "ReferenceAxes": "xyz",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejection": False
+        }
+    }
+    ```
+
+-   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_desc-wm_csd.nii.gz
+                sub-01_desc-wm_csd.json
+                sub-01_desc-gm_csd.nii.gz
+                sub-01_desc-gm_csd.json
+                sub-01_desc-csf_csd.nii.gz
+                sub-01_desc-csf_csd.json
+                sub-01_csd.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+
+    Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
+
+    ```JSON
+    {
+        "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+        "Shells": [ 0, 1000, 2000, 3000 ],
+        "Parameters": {
+            "SphericalHarmonicBasis": "MRtrix3",
+            "NonNegativityConstraint": "hard"
+        }
+    }
+    ```
+
+    Contents of JSON file "`sub-01_desc-wm_csd.json`":
+
+    ```JSON
+    {
+        "OrientationRepresentation": "sh",
+        "ReferenceAxes": "xyz",
+        "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
+                                 [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
+                                 [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
+                                 [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
+        "SphericalHarmonicDegree": 8,
+        "Tissue": "White matter"
+    }
+    ```
+
+    Contents of JSON file "`sub-01_desc-gm_csd.json`":
+
+    ```JSON
+    {
+        "OrientationRepresentation": "sh",
+        "ReferenceAxes": "xyz",
+        "ResponseFunctionZSH": [ [ 1041.0 ],
+                                 [ 436.6 ],
+                                 [ 224.9 ],
+                                 [ 128.8 ] ],
+        "SphericalHarmonicDegree": 0,
+        "Tissue": "Grey matter"
+    }
+    ```
+
+-   A NODDI fit:
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_parameter-icvf_noddi.nii.gz
+                sub-01_parameter-isovf_noddi.nii.gz
+                sub-01_parameter-od_noddi.nii.gz
+                sub-01_parameter-direction_noddi.nii.gz
+                sub-01_parameter-direction_noddi.json
+                sub-01_noddi.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#data-3vector))
+
+    Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
+
+    ```JSON
+    {
+        "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+        "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
+    }
+    ```
+
+    Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
+
+    ```JSON
+    {
+        "OrientationRepresentation": "3vector",
+        "ReferenceAxes": "???"
+    }
+    ```
+
+-   An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
+    bootstrap realisations):
+
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_desc-mean_parameter-bzero_bs.nii.gz
+                sub-01_desc-mean_parameter-dmean_bs.nii.gz
+                sub-01_desc-mean_parameter-dstd_bs.nii.gz
+                sub-01_desc-mean_parameter-sticks_bs.nii.gz
+                sub-01_desc-mean_parameter-sticks_bs.json
+                sub-01_desc-merged_parameter-sticks_bs.nii.gz
+                sub-01_desc-merged_parameter-sticks_bs.json
+                sub-01_bs.json
+    ```
+
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+
+    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
+    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
+    files are identical):
+
+    ```JSON
+    {
+        "OrientationRepresentation": "spherical",
+        "ReferenceAxes": "ijk"
+    }
+    ```
+
+    Contents of JSON file "`sub-01_bs.json`":
+
+    ```JSON
+    {
+        "Model": "Ball-And-Sticks model using FSL bedpostx",
+        "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3,
+            "Samples": 50
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    }
+    ```
 
 -----
 

From a5f45147916313763a7faa0b5f219e570624d762 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:18:59 +1100
Subject: [PATCH 19/65] BEP016: More formatting conformity changes

---
 .../05-diffusion-derivatives.md               | 54 +++----------------
 1 file changed, 6 insertions(+), 48 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 281c7e70..8b7b2d52 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -267,9 +267,9 @@ ideally be integrated in a future version of the specification.
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors](#data-param) image with parameter name "`all`" with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                                                              |
-| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#data-pdf)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors](#data-param) image with parameter name "`all`" with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                     |
+| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#data-pdf)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#data-param) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One [scalar](#data-scalar) image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -288,7 +288,7 @@ the following key/value pairs irrespective of the particular model:
 | Mask             | OPTIONAL. String. Name of image that was used as a binary mask to specify those voxels for which the model was fit.                                                                          |
 | ModelDescription | OPTIONAL. String. Extended information to describe the model.                                                                                                                                |
 | ModelURL         | OPTIONAL. String. URL to the implementation of the specific model utilized.                                                                                                                  |
-| Parameters       | OPTIONAL. Dictionary. [Input](#paramdef-input) model parameters that are constant across the image (see examples below).                                                                    |
+| Parameters       | OPTIONAL. Dictionary. [Input](#paramdef-input) model parameters that are constant across the image (see examples below).                                                                     |
 
 #### Model bootstrapping
 
@@ -319,49 +319,35 @@ Reserved keywords for models built into the specification are as follows:
 -   `bs` :
 
     -   `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
-    
     -   `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
-    
     -   `ModelBall`: String. Model used to describe the "ball" component in the model.
-    
     -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
 
 -   `csa` :
 
     -   `SphericalHarmonicOrder` : value
-    
     -   `Smoothing` : value
-    
     -   `Basis` : value
 
 -   `csd`:
 
     -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
-    
     -   `ResponseFunctionZSH`: Two options:
-    
+
         -   Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
-        
         -   Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
-        
+
     -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-    
     -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
-    
     -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
-    
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
 -   `dsi` :
 
     -   `GridSize` : value
-    
     -   `RStart` : value
-    
     -   `RStep` : value
-    
     -   `REnd` : value
-    
     -   `FilterWidth` : value
 
 -   `dti` :
@@ -371,73 +357,45 @@ Reserved keywords for models built into the specification are as follows:
 -   `forecast` :
 
     -   `Sphere` : value
-    
     -   `DecAlg` : value
-    
     -   `LambdaLb` : value
-    
     -   `SphericalHarmonicsOrder` : value
 
 -   `mapmri` :
 
     -   `RadialOrder` : value
-    
     -   `LaplacianRegularization` : bool
-    
     -   `LaplacianWeighting` : value
-    
     -   `PositivityConstraint` : bool
-    
     -   `Tau` : value
-    
     -   `ConstrainE0` : value
-    
     -   `PositiveConstraint` : value
-    
     -   `PosGrid` : value
-    
     -   `PosRadius` : value
-    
     -   `AnisotropicScaling` : bool
-    
     -   `EigenvalueThreshold` : value
-    
     -   `PosGrid` : value
-    
     -   `BvalThreshold` : value
-    
     -   `DTIScaleEstimation` : bool
-    
     -   `StaticDiffusivity` : value
 
 -   `noddi`:
 
     -   `DPar` : value
-    
     -   `DIso` : value
-    
     -   `Lambda1` : value
-    
     -   `Lambda2` : value
 
 -  `shore` :
 
     -   `RadialOrder` : value
-    
     -   `Zeta` : value
-    
     -   `LambdaN` : value
-    
     -   `LambdaL` : value
-    
     -   `Tau` : value
-    
     -   `ConstrainE0` : value
-    
     -   `PositiveConstraint` : value
-    
     -   `PosGrid` : value
-    
     -   `PosRadius` : value
 
 ### Extrinsic model parameters

From 0dccc99106693af7dbaa0c8646b786b304f61d8b Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:23:33 +1100
Subject: [PATCH 20/65] BEP016: More formatting conformity changes

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 8b7b2d52..78f45af0 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -332,14 +332,18 @@ Reserved keywords for models built into the specification are as follows:
 -   `csd`:
 
     -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
+    
     -   `ResponseFunctionZSH`: Two options:
 
         -   Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
         -   Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
 
     -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
+    
     -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+    
     -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
+    
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
 -   `dsi` :
@@ -386,7 +390,7 @@ Reserved keywords for models built into the specification are as follows:
     -   `Lambda1` : value
     -   `Lambda2` : value
 
--  `shore` :
+-   `shore` :
 
     -   `RadialOrder` : value
     -   `Zeta` : value
@@ -482,9 +486,9 @@ another.
 
         *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-        | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | ...  |
         | --------------------- | --: | --: | --: | --: | --: | :--: |
-        | ***N***               |   1 |   6 |  15 |  28 |  45 | etc. |
+        | ***N***               | 1   | 6   | 15  | 28  | 45  | etc. |
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
@@ -493,9 +497,9 @@ another.
 
         *N* = 1 + (*l<sub>max</sub>* / 2)
 
-        | ***l<sub>max</sub>*** |  0  |  2  |  4  |  6  |  8  | ...  |
+        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | ...  |
         | --------------------- | --: | --: | --: | --: | --: | :--: |
-        | ***N***               |   1 |   2 |  3  |  4  |  5  | etc. |
+        | ***N***               | 1   | 2   | 3   | 4   | 5   | etc. |
 
 -   `Descoteaux`
 
@@ -682,13 +686,13 @@ another.
     }
     ```
 
------
+---
 
 <a name="diffusivity"><sup>1</sup></a>: For example, for free water in body
 temperature, the diffusivity in units of \mu m<sup>2</sup>.ms<sup>-1</sup>
 should be approximately 3.0.
 
------
+---
 
 <a name="aganj2010">\[Aganj2010\]</a>: Aganj et al. 2010
 

From f237b8b44fde9c2973ab2bf894c4bd58260e4d2b Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:27:59 +1100
Subject: [PATCH 21/65] BEP016: Attempted fixes to table cell padding

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 78f45af0..e614e99d 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -332,18 +332,18 @@ Reserved keywords for models built into the specification are as follows:
 -   `csd`:
 
     -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
-    
+
     -   `ResponseFunctionZSH`: Two options:
 
         -   Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
         -   Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
 
     -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
-    
+
     -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
-    
+
     -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
-    
+
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
 -   `dsi` :
@@ -486,9 +486,9 @@ another.
 
         *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | ...  |
-        | --------------------- | --: | --: | --: | --: | --: | :--: |
-        | ***N***               | 1   | 6   | 15  | 28  | 45  | etc. |
+        | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | ...  |
+        | --------------------- |--:|--:|--: |--: |--: | :--: |
+        | ***N***               | 1 | 6 | 15 | 28 | 45 | etc. |
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
@@ -497,9 +497,9 @@ another.
 
         *N* = 1 + (*l<sub>max</sub>* / 2)
 
-        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | ...  |
-        | --------------------- | --: | --: | --: | --: | --: | :--: |
-        | ***N***               | 1   | 2   | 3   | 4   | 5   | etc. |
+        | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | ...  |
+        | --------------------- |--:|--:|--:|--:|--:| :--: |
+        | ***N***               | 1 | 2 | 3 | 4 | 5 | etc. |
 
 -   `Descoteaux`
 

From 4c5e388ac3920db19bf33b0474578bc45cc2016a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:30:11 +1100
Subject: [PATCH 22/65] BEP016: Minor fix to tractography derivatives for CI
 pass

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

diff --git a/src/05-derivatives/05-diffusion-derivatives-tractography.md b/src/05-derivatives/05-diffusion-derivatives-tractography.md
index 671be71d..6fc5da9c 100644
--- a/src/05-derivatives/05-diffusion-derivatives-tractography.md
+++ b/src/05-derivatives/05-diffusion-derivatives-tractography.md
@@ -65,27 +65,27 @@ The JSON sidecar contains the following key/value pairs:
 
 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)                                  |
+| **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                                                 |
+| **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 158586f1613731d1574ae50be07868bf1d3353d4 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 22 Nov 2021 15:45:44 +1100
Subject: [PATCH 23/65] BEP016: Modify nomenclature around MRtrix3 SH
 coefficients

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 98ffc66f..45ec294c 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -476,28 +476,28 @@ another.
         conjugate.
 
     -   Antipodally symmetric: all basis functions with odd degree are
-        assumed zero; `AntipodalSymmetry` MUST NOT be set to `True`.
+        assumed zero; `AntipodalSymmetry` MUST NOT be set to `False`.
 
     -   Utilised basis functions:
 
         ![MRtrix3 SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
 
-    -   Mapping between image volume *V<sub>lm</sub>* and spherical harmonic basis
-        function coefficient *c<sub>lm</sub>*:
-
-        *V<sub>lm</sub>* = (*l*(*l*+1) / 2) + *m*
-
-        | ***V<sub>lm</sub>*** | ***c<sub>lm</sub>***              |
-        | -------------------- | --------------------------------- |
-        | 0                    | *l* = 0, *m* = 0                  |
-        | 1                    | *l* = 2, *m* = 2 (imaginary part) |
-        | 2                    | *l* = 2, *m* = 1 (imaginary part) |
-        | 3                    | *l* = 2, *m* = 0                  |
-        | 4                    | *l* = 2, *m* = 1 (real part)      |
-        | 5                    | *l* = 2, *m* = 2 (real part)      |
-        | 6                    | *l* = 4, *m* = 4 (imaginary part) |
-        | 7                    | *l* = 4, *m* = 3 (imaginary part) |
-        | ...                  | etc.                              |
+    -   Mapping between image volume *V* and spherical harmonic basis
+        function coefficient *Y<sub>l,m</sub>*:
+
+        *V<sub>l,m</sub>* = (*l*(*l*+1) / 2) + *m*
+
+        | ***V*** | **Coefficient**    |
+        | ------- | ------------------ |
+        | 0       | *Y<sub>0,0</sub>*  |
+        | 1       | *Y<sub>2,-2</sub>* |
+        | 2       | *Y<sub>2,-1</sub>* |
+        | 3       | *Y<sub>2,0</sub>*  |
+        | 4       | *Y<sub>2,1</sub>*  |
+        | 5       | *Y<sub>2,2</sub>*  |
+        | 6       | *Y<sub>4,-4</sub>* |
+        | 7       | *Y<sub>4,-3</sub>* |
+        | ...     | etc.               |
 
     -   Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
         and number of image volumes *N*:

From 6ab71309f8e8fced42afa11fdc9eed3a3d07027b Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 23 Nov 2021 11:38:02 +1100
Subject: [PATCH 24/65] BEP016: Revise preprocessed DWI data example

- Provide basic instructions rather than elaborating on rare use cases.
- Remove JSON dictionary on preprocessing steps utilised as these relate to provenance and are therefore out of scope.
Proposal for addressing bids-standard/bids-bep016#25.
---
 .../05-diffusion-derivatives.md               | 51 ++++++++-----------
 1 file changed, 20 insertions(+), 31 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index e614e99d..022eb085 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -2,44 +2,33 @@
 
 ## Preprocessed diffusion-weighted images
 
-Multiple different versions of preprocessing can be stored for the same source
-data. To distinguish them from each other, the `desc` filename keyword can be
-used. Details of preprocessing performed for each variation of the processing
-should be included in the pipeline documentation.
+-   As with [raw diffusion imaging data](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#required-gradient-orientation-information),
+    inclusion of gradient orientation information is REQUIRED. While
+    [the inheritance principle](../02-common-principles.md#the-inheritance-principle)
+    applies, it is common for DWI preprocessing to include rotation of
+    gradient orientations according to subject motion, so series-specific
+    gradient information is typically expected.
+
+-   As per [file naming conventions for BIDS Derivatives](01-introduction.md#file-naming-conventions),
+    preprocessed DWI data must not possess the same name as that of the raw
+    DWI data. It is RECOMMENDED to disambiguate through use of the key-value
+    "`_desc-preproc`".
+
+-   As per [common data types](02-common-data-types.md) for derivative data, a
+    JSON sidecar file is REQUIRED due to the REQUIRED `SkullStripped` field.
+
+Template:
 
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
-            <source_keywords>[_space-<space>][_desc-<label>]_dwi.json
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.nii[.gz]
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvals
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvecs
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.json
 ```
 
-The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
-see [Common Data Types](02-common-data-types.md)), and MAY additionally be used to
-store information about what preprocessing options were used (for example
-whether denoising was performed, corrections applied for field inhomogeneity /
-gradient non-linearity / subject motion / eddy currents, etc.).
-
-Additional reserved JSON metadata fields:
-
-| **Key name**                           | **Description**                                                                                                                                   |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Denoising                              | OPTIONAL. String. Denoising method                                                                                                                |
-| GibbsRingingCorrection                 | OPTIONAL. Boolean. Removal of Gibbs ringing artifacts                                                                                             |
-| MotionCorrection                       | OPTIONAL. String. Motion correction; allowed values: `none`, `volume`, `slice`                                                                    |
-| EddyCurrentCorrection                  | OPTIONAL. String. Eddy current distortion correction; reserved values: `none`, `linear`, `quadratic`, `cubic`                                     |
-| IntensityNormalizationMethod           | OPTIONAL. String. Method (if any) used for intensity normalization                                                                                |
-| FieldInhomogeneityEstimation           | OPTIONAL. String. Method (if any) used for estimation of the B0 inhomogeneity field; reserved values: `multiecho`, `phaseencode`, `registration`  |
-| FieldInhomogeneityCorrection           | OPTIONAL. String. Correction for geometric distortions arising from B0 magnetic field inhomogeneity; reserved values: `none`, `static`, `dynamic` |
-| GradientNonLinearityGeometryCorrection | OPTIONAL. Boolean. Correction for geometric distortions arising from non-linearity of gradients                                                   |
-| GradientNonLinearityQSpaceCorrection   | OPTIONAL. Boolean. Correction for spatial inhomogeneity of diffusion sensitisation gradient strength                                              |
-| SliceDropoutDetection                  | OPTIONAL. Boolean. Detection of signal dropout in acquired slices during pre-processing                                                           |
-| SliceDropoutReplacement                | OPTIONAL. Boolean. Replacement of image data within slices containing signal dropout with predicted values                                        |
-| BiasFieldCorrectionMethod              | OPTIONAL. String. Method (if any) used for correction of B1 RF field inhomogeneity                                                                |
-
 ## Diffusion models
 
 Diffusion MRI can be modeled using various paradigms to extract more

From 4c7b81ba4d4b362fad23f07c3f814ae57d1638b5 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 30 Nov 2021 15:57:37 +1100
Subject: [PATCH 25/65] BEP016: Remove SH Descoteaux placeholder

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 45ec294c..98e953da 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -340,7 +340,7 @@ Reserved keywords for models built into the specification are as follows:
 
     -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
 
-    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3`, `Descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
 
     -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
 
@@ -444,7 +444,7 @@ in order to produce a [directionally-encoded colour](#data-dec),
 | `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
 | `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `pdf`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.         |
 | `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3`, `Descoteaux` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                            |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                          |
 | `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
 
 If `AntipodalSymmetry` is True, then no constraints are imposed with respect
@@ -519,10 +519,6 @@ another.
         | --------------------- |--:|--:|--:|--:|--:| :--: |
         | ***N***               | 1 | 2 | 3 | 4 | 5 | etc. |
 
--   `Descoteaux`
-
-    ***TODO***
-
 ## Demonstrative examples
 
 -   A basic Diffusion Tensor fit:

From 80e19fef32c90518ec8946627dc657f8f2bb61d5 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 1 Dec 2021 11:27:57 +1100
Subject: [PATCH 26/65] BEP016: Remove majority of models

Introduction and review of most models are intended to be deferred as per bids-specification/bids-bep016#39.
---
 .../05-diffusion-derivatives.md               | 172 ++----------------
 1 file changed, 15 insertions(+), 157 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index e614e99d..dc01709d 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -244,10 +244,6 @@ interpretation of that information; see [orientation specification](#orientation
     each voxel are provided; these directions MUST themselves be provided
     in the associated sidecar JSON file (see [orientation specification](#orientation-specification)).
 
-1.  <a name="data-pdf">*Probability Distribution Functions (PDFs)*</a>:
-
-    ***TODO***
-
 1.  <a name="data-param">*Parameter vectors*</a>:
 
     4D image containing, for every image voxel, data corresponding to some
@@ -265,18 +261,8 @@ ideally be integrated in a future version of the specification.
 | Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `csa`       | Constant Solid Angle \[[Aganj2010](#aganj2010)\]                                                                                                | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `dki`       | Diffusion Kurtosis Imaging \[[Jensen2005](#jensen2005)\]                                                                                        | Single [parameter vectors](#data-param) image with parameter name "`all`" with 21 volumes in the order: *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>* (*D* is the diffusion tensor, *W* is the kurtosis tensor)<br>OR<br>6 diffusion tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>15 kurtosis tensor coefficients as [parameter vectors](#data-param) image with parameter name "`kurtosis`";<br>Optional: estimated *b*=0 intensity as scalar image with parameter name "`bzero`"                                     |
-| `dsi`       | Diffusion Spectrum Imaging \[[Wedeen2008](#wedeen2008)\],\[[Paquette2017](paquette2017)\]                                                       | [Probability distribution functions](#data-pdf)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `forecast`  | Fiber ORientation Estimated using Continuous Axially Symmetric Tensors \[[Zuchelli2017](#zuchelli2017)\]                                        | [Spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `fwdti`     | Free water DTI \[[Hoy2015](#hoy2015)\]                                                                                                          | One [parameter vectors](#data-param) 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>* (*Dc* is the free-water-corrected diffusion tensor);<br>One [scalar](#data-scalar) image with parameter name "`fwf`" corresponding to the estimated free water fraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `mapmri`    | Mean Apparent Propagator MRI \[[Ozarslan2013](#ozarslan2013)\]                                                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `noddi`     | Neurite Orientation Dispersion and Density Imaging \[[Zhang2012](#zhang2012)\],\[[Daducci2015](#daducci2015)\]                                  | Three [scalar](#data-scalar) images, with parameter names equal to {"`icvf`", "`isovf`", "`od`"} (ICVF is the “intracellular volume fraction” (also known as NDI); ISOVF is the "isotropic component volume fraction"; OD is the “orientation dispersion” (the variance of the Watson distribution; also known as ODI));<br>One [3-vectors](#data-3vector) image with parameter name "`direction`" to provide the estimated fibre orientation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `qbi`       | Q-Ball Imaging \[[Tuch2004](#tuch2004)\], \[[Hess2006](#hess2006)\]                                                                             | Single [amplitudes](#data-amp) image<br>OR<br>Single [spherical harmonics](#data-sh) image                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `shore`     | Simple Harmonic Oscillator-based Reconstruction and Estimation \[[Ozarslan2008](#ozarslan2008)\]                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `wmti`      | White Matter Tract Integrity \[[Fieremans2011](#fieremans2011)\]                                                                                | One [parameter vectors](#data-param) image with parameter name "`coeffs`", with 33 volumes in the order: *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>* (*D* is the diffusion tensor and *W* is the kurtosis tensor);<br>One [scalar](#data-scalar) image with parameter name "`awf`", representing the estimated axonal water fraction |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:
@@ -323,12 +309,6 @@ Reserved keywords for models built into the specification are as follows:
     -   `ModelBall`: String. Model used to describe the "ball" component in the model.
     -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
 
--   `csa` :
-
-    -   `SphericalHarmonicOrder` : value
-    -   `Smoothing` : value
-    -   `Basis` : value
-
 -   `csd`:
 
     -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
@@ -346,88 +326,27 @@ Reserved keywords for models built into the specification are as follows:
 
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
--   `dsi` :
-
-    -   `GridSize` : value
-    -   `RStart` : value
-    -   `RStep` : value
-    -   `REnd` : value
-    -   `FilterWidth` : value
-
 -   `dti` :
 
     -   `RESTORESigma`: Float
 
--   `forecast` :
-
-    -   `Sphere` : value
-    -   `DecAlg` : value
-    -   `LambdaLb` : value
-    -   `SphericalHarmonicsOrder` : value
-
--   `mapmri` :
-
-    -   `RadialOrder` : value
-    -   `LaplacianRegularization` : bool
-    -   `LaplacianWeighting` : value
-    -   `PositivityConstraint` : bool
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
-    -   `AnisotropicScaling` : bool
-    -   `EigenvalueThreshold` : value
-    -   `PosGrid` : value
-    -   `BvalThreshold` : value
-    -   `DTIScaleEstimation` : bool
-    -   `StaticDiffusivity` : value
-
--   `noddi`:
-
-    -   `DPar` : value
-    -   `DIso` : value
-    -   `Lambda1` : value
-    -   `Lambda2` : value
-
--   `shore` :
-
-    -   `RadialOrder` : value
-    -   `Zeta` : value
-    -   `LambdaN` : value
-    -   `LambdaL` : value
-    -   `Tau` : value
-    -   `ConstrainE0` : value
-    -   `PositiveConstraint` : value
-    -   `PosGrid` : value
-    -   `PosRadius` : value
-
 ### Extrinsic model parameters
 
-| `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources                          | Unit or scale                                                  |
-| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------- |
-| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `ak`                | Axial kurtosis                                                         | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#data-scalar)                       | { `csd` }                                       | Unitless                                                       |
-| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `dki`, `dti`, `fwdti`, `wmti` }               | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | Proportion \[0.0-1.0\]                                         |
-| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#data-scalar)                       | { `bs` }                                        | Volume fraction \[0.0-1.0\]                                    |
-| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#data-scalar)                       | { `csa`, `csd`, `forecast`, `mapmri`, `shore` } | Proportion \[0.0-1.0\]                                         |
-| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `mk`                | Mean kurtosis                                                          | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `dki`, `dti`, `fwdti`, `wmti` }               |                                                                |
-| `msd`               | Mean-Squared Displacement                                              | [Scalar](#data-scalar)                       | { `mapmri`, `shore` }                           |                                                                |
-| `pdf`               | Diffusion propagator                                                   | [3-vectors](#data-3vector)                   |                                                 |                                                                |
-| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#data-3vector)                   | { `csa`, `csd`, `forecast`, `shore` }           | Same units as ODF                                              |
-| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `dki`, `dti`, `forecast`, `fwdti`, `wmti` }   | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `rk`                | Radial kurtosis                                                        | [Scalar](#data-scalar)                       | { `dki`, `wmti` }                               | Unitless                                                       |
-| `rtap`              | Return To Axis Probability                                             | [Scalar](#data-scalar)                       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `rtop`              | Return To Origin Probability                                           | [Scalar](#data-scalar)                       | { `shore` }                                     | Probability \[0.0-1.0\]                                        |
-| `rtpp`              | Return To Plane Probability                                            | [Scalar](#data-scalar)                       | { `mapmri` }                                    | Probability \[0.0-1.0\]                                        |
-| `tort`              | Tortuosity of extra-cellular space                                     | [Scalar](#data-scalar)                       | { `dki` }                                       |                                                                |
+| `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources | Unit or scale                                                  |
+| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------------------------- |
+| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#data-scalar)                       | { `csd` }              | Unitless                                                       |
+| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
+| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
+| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
+| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `dti` }              | Proportion \[0.0-1.0\]                                         |
+| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#data-scalar)                       | { `bs` }               | Volume fraction \[0.0-1.0\]                                    |
+| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#data-scalar)                       | { `csd` }              | Proportion \[0.0-1.0\]                                         |
+| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
+| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#data-3vector)                   | { `csd` }              | Same units as ODF                                              |
+| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
 
 While not explicitly included in the table above, *any* [scalar](#data-scalar)
 [extrinsic](paramdef-extrinsic) parameter can theoretically be combined
@@ -596,43 +515,6 @@ another.
     }
     ```
 
--   A NODDI fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_parameter-icvf_noddi.nii.gz
-                sub-01_parameter-isovf_noddi.nii.gz
-                sub-01_parameter-od_noddi.nii.gz
-                sub-01_parameter-direction_noddi.nii.gz
-                sub-01_parameter-direction_noddi.json
-                sub-01_noddi.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_parameter-icvf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-isovf_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-od_noddi.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_parameter-direction_noddi.nii.gz`": *I*x*J*x*K*x3 ([3-vectors](#data-3vector))
-
-    Contents of file "`sub-01_noddi.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
-
-    ```JSON
-    {
-        "Model": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
-        "ModelURL": "https://www.nitrc.org/projects/noddi_toolbox"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_parameter-direction_noddi.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "3vector",
-        "ReferenceAxes": "???"
-    }
-    ```
-
 -   An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
     bootstrap realisations):
 
@@ -694,8 +576,6 @@ should be approximately 3.0.
 
 ---
 
-<a name="aganj2010">\[Aganj2010\]</a>: Aganj et al. 2010
-
 <a name="basser1994">\[Basser1994\]</a>: Basser et al. 1994
 
 <a name="basser1996">\[Basser1996\]</a>: Basser et al. 1996
@@ -706,38 +586,16 @@ should be approximately 3.0.
 
 <a name="calamante2015">\[Calamante2015\]</a>: Calamante et al. 2015
 
-<a name="daducci2015">\[Daducci2015\]</a>: Daducci et al. 2015
-
 <a name="descoteaux2009">\[Descoteaux2009\]</a>: Descoteaux et al. 2009
 
-<a name="fieremans2011">\[Fieremans2011\]</a>: Fieremans et al. 2011
-
-<a name="hess2006">\[Hess2006\]</a>: Hess et al. 2006
-
-<a name="hoy2014">\[Hoy2014\]</a>: Hoy et al. 2014
-
 <a name="jbabdi2012">\[Jbabdi2012\]</a> Jbabdi et al. 2012
 
-<a name="jensen2005">\[Jensen2005\]</a>: Jensen et al. 2005
-
 <a name="jeurissen2014">\[Jeurissen2014\]</a>: Jeurissen et al. 2014
 
-<a name="ozarslan2008">\[Ozarslan2008\]</a>: Ozarslan et al. 2008
-
-<a name="ozarslan2013">\[Ozarslan2013\]</a>: Ozarslan 2013
-
-<a name="paquette2017">\[Paquette2017\]</a>: Paquette et al 2017
-
 <a name="pajevic1999">\[Pajevic1999\]</a>: Pajevic et al 1999
 
 <a name="tournier2007">\[Tournier2007\]</a>: Tournier et al. 2007
 
 <a name="tuch2004">\[Tuch2004\]</a>: Tuch 2004
 
-<a name="wedeen2008">\[Wedeen2008\]</a>: Wedeen et al. 2008
-
 <a name="westin1997">\[Westin1997\]</a>: Westin 1997
-
-<a name="zhang2012">\[Zhang2012\]</a>: Zhang et al. 2012
-
-<a name="zuchelli2017">\[Zuchelli2017\]</a>: Zuchelli et al. 2017

From beb7a16bad2f5485ed6171a33e77e8df2ffa2cbd Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 1 Dec 2021 11:34:13 +1100
Subject: [PATCH 27/65] BEP016: Formatting fix following removal of models

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index dc01709d..a173204f 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -258,11 +258,11 @@ intrinsic or extrinsic parameters. 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 future version of the specification.
 
-| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
+| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
+| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:

From fcff8aca0503fa7e7790ceecb70c189b63eb2fe9 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 2 Dec 2021 11:59:23 +1100
Subject: [PATCH 28/65] BEP016: Strip out tractography content

---
 .../05-diffusion-derivatives-tractography.md  | 137 ------------------
 1 file changed, 137 deletions(-)
 delete mode 100644 src/05-derivatives/05-diffusion-derivatives-tractography.md

diff --git a/src/05-derivatives/05-diffusion-derivatives-tractography.md b/src/05-derivatives/05-diffusion-derivatives-tractography.md
deleted file mode 100644
index 6fc5da9c..00000000
--- a/src/05-derivatives/05-diffusion-derivatives-tractography.md
+++ /dev/null
@@ -1,137 +0,0 @@
-## Describing tractography
-
-Tractography normally generates one of two primary file types: tractograms or
-NIfTi files containing maps. Tractograms are files containing a collection of
-streamlines, which are objects describing the path of idealized brain fiber
-fascicles (ensembles of neural fibers that travel together). Tractography
-visitation maps contain 3D spatial histograms of the number / fraction of
-streamlines intersecting each voxel, but do not contain the individual
-streamlines trajectories themselves. Two tractogram file formats are supported;
-tractography visitation maps should be saved as NIfTIs.
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
-```
-
-### Filename keys
-
-`desc` (optional) – A way to refer to a specific instance of the tractography
-process. The combination of tractography methods and parameters that were used
-to create this tractography result should be described in the associated JSON
-file.
-
-`subset` (optional) – A label descriptor for the the subset of streamlines
-included in this file; if not specified, a whole brain tractography is assumed
-(a tractogram). Example of subsets can be `short` if only short streamlines were
-kept, or `subsampled50` if only 50% of the streamlines were kept.
-
-### File formats
-
--   [.trk - Diffusion Toolkit (+TrackVis)](https://web.archive.org/web/20190103230122/http://www.trackvis.org/docs/?subsect=fileformat)
--   [.tck - MRtrix](https://web.archive.org/web/20190103230209/https://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html#tracks-file-format-tck)
-
-### JSON Metadata
-
-We have two main classes of tractography algorithms: Global or Local
-tractography, each with various supported algorithms.
-
-| Class  | Algorithms | Reference                                                                                                                            |
-| ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| LOCAL  | PROB       | Sherbondy, A.J., et al. (2008); Tournier J.D. et al. (2012); Behrens et al. (2007)                                                   |
-| LOCAL  | DET        | Conturo, T. et al. (1999); Mori, S. et al. (1999)                                                                                    |
-| LOCAL  | EUDX       | Garyfallidis et al. (2010); Mori, S. et al. (1999)                                                                                   |
-| LOCAL  | FACT       | Jiang, H. et al. (2005)                                                                                                              |
-| LOCAL  | STT        | Lazar, M. et al. (2003)                                                                                                              |
-| LOCAL  | NULL       | Morris et al. (2008)                                                                                                                 |
-| GLOBAL | UKF        | Malcolm J-G. et al. (2009)                                                                                                           |
-| GLOBAL | SpinGlass  | Fillard P. et al. (2009)                                                                                                             |
-| GLOBAL | ENS        | Takemura et al. (2016)                                                                                                               |
-| GLOBAL | Other      | Mangin, J.F. et al. (2013); Aganj, I. et al. (2011); Neher, P.F. et al. (2012); Jbabdi, S., et al. (2007); Reisert, M. et al. (2011) |
-
-The JSON sidecar contains the following key/value pairs:
-
-| **Key name**       | **Description**                                                                                                      |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| TractographyClass  | REQUIRED. Allowed values: `local`, `global`                                                                          |
-| TractographyMethod | REQUIRED. Allowed values: `probabilistic`,`deterministic`,`eudx`,`fact`,`stt`,`null`,`ukf`,`spinglass`,`ens`,`other` |
-| Count              | REQUIRED. integer                                                                                                    |
-| Description        | OPTIONAL. string                                                                                                     |
-| Constraints        | OPTIONAL. A dictionary containing various ways in which the tractography outcome is constrained (see below).         |
-| Parameters         | OPTIONAL. A dictionary of model parameters (see below).                                                              |
-| Seeding            | OPTIONAL. A dictionary describing how streamlines were initialised (see below).                                      |
-
-RECOMMENDED to appear within the "`Constraints`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**    | **Description**                                                                             |
-| --------------- | ------------------------------------------------------------------------------------------- |
-| AnatomicalType  | {`ACT`,`CMC`}                                                                               |
-| AnatomicalImage | string (name of anatomical tissue segmentation image)                                       |
-| Include         | list of names of inclusion ROIs (streamlines must intersect all)                            |
-| OrderedInclude  | list of names of ordered inclusion ROIs (streamlines must intersect all in order specified) |
-| Exclude         | list of names of exclusion ROIs (streamlines must not intersect any)                        |
-| Mask            | list of names of mask ROIs (streamlines must exist within)                                  |
-
-RECOMMENDED to appear within the "`Parameters`" field when "`TractographyClass`" is "`local`":
-
-| **Key name**     | **Description**                                      |
-| ---------------- | ---------------------------------------------------- |
-| Units            | {`mm`,`norm`} (applies to all within "`Parameters`") |
-| StepSize         | value                                                |
-| AngleCurvature   | value (maximum angle per step)                       |
-| RadiusCurvature  | value (minimal radius of curvature)                  |
-| MinimumLength    | value                                                |
-| MaximumLength    | value                                                |
-| IntegrationOrder | integer                                              |
-| Unidirectional   | bool                                                 |
-
-RECOMMENDED to appear within the "Seeding" field when `TractographyClass` is `local`:
-
-| **Key name** | **Description**                                                                                                          |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| SourceType   | {`sphere`,`voxels`,`surface`,`odf`}                                                                                      |
-| Location     | values: If "`SourceType`" is "`sphere`", provide a 4-vector containin the XYZ location and radius in mm of the sphere    |
-| Name         | string: If "`SourceType`" is not "`sphere`", give the filename from which seeds were derived                             |
-| CountType    | {`global`,`local`} (i.e. does Count reflect a count per voxel / vertex, or a single count for the entire reconstruction) |
-| Count        | integer                                                                                                                  |
-
-Example:
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_desc-DET_tractography.trk
-            sub-01_desc-DET_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "local",
-    "TractographyMethod": "deterministic",
-    "Parameters": {
-        "StepSize": 0.5
-    }
-}
-```
-
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            sub-01_subset-shortfibers_tractography.trk
-            sub-01_subset-shortfibers_tractography.json
-```
-
-```JSON
-{
-    "TractographyClass": "global",
-    "TractographyMethod": "UKF",
-    "Description": "UKF tracking where only short fibers were kept.",
-    "Parameters": {
-        "MaximumLength": 50.0
-    }
-}
-```

From bab290027be85c5c61f7033f3a15c455cda31250 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Wed, 1 Dec 2021 20:06:55 -0800
Subject: [PATCH 29/65] Fixes a typo caught by codespell

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 5b28531a..d697a98f 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -271,7 +271,7 @@ Results of model bootstrapping can be provided by concatenating multiple
 realisations of model intrinsic parameters along an additional image axis.
 
 The corresponding sidecar JSON file may include dictionary field
-"`BootstrapParameters`", descibing those input parameters specific to
+"`BootstrapParameters`", describing those input parameters specific to
 the determination and export of multiple realisations of the model fit
 in each image voxel.
 

From c9d2748bcc7aa6373d3acd02ec413d07fc38af2a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 2 Dec 2021 16:09:04 +1100
Subject: [PATCH 30/65] BEP016: Initial draft of common filename suffix "model"

---
 .../05-diffusion-derivatives.md               | 157 +++++++++---------
 1 file changed, 78 insertions(+), 79 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 5b28531a..d77af8ea 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -54,17 +54,17 @@ Throughout this document, the term "parameter" is used to refer to
 multiple distinct sources of information. The distinction between
 these uses is defined thus:
 
-1.  <a name="paramdef-input">*Input*</a> model parameter:
+1.  <a name="paramdef-input">*Input*</a> parameter:
 
     Value or non-numerical setting that influences the conformation
     of the diffusion model to the empirical diffusion-weighted data.
 
-1.  <a name="paramdef-intrinsic">*Intrinsic*</a> model parameter:
+1.  <a name="paramdef-model">*Model*</a> parameter:
 
     Value that is the direct result of fitting the diffusion model to the
     empirical diffusion-weighted data.
 
-1.  <a name="paramdef-extrinsic">*Extrinsic*</a> model parameter:
+1.  <a name="paramdef-derived">Model-*derived*</a> parameter:
 
     Value that can be calculated directly from previously estimated
     intrinsic model parameters, without necessitating reference to
@@ -72,8 +72,8 @@ these uses is defined thus:
 
 For example, consider a diffusion tensor model fit: the number of
 iterations in the optimisation algorithm would be an *input* parameter;
-the six unique diffusion tensor coefficients would be the *intrinsic*
-parameters; the Fractional Anisotropy (FA) would be an *extrinsic*
+the six unique diffusion tensor coefficients would be the *model*
+parameters; the Fractional Anisotropy (FA) would be a *model-derived*
 parameter (as it is calculated from the diffusion tensor coefficients
 rather than the image data).
 
@@ -83,47 +83,40 @@ rather than the image data).
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam1>_<model>.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam2>_<model>.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
-
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.json]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<param1>_model.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<param1>_model.json
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<param2>_model.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<param2>_model.json
+            <source_keywords>[_space-<space>][_desc-<label>]_model.json
+
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<parama>_mdp.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<parama>_mdp.json]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<paramb>_mdp.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<paramb>_mdp.json]
 ```
 
--   Field "`<model>`" is a unique identifier corresponding to the particular
-    diffusion model. If the particular diffusion model is one that is included
-    in this specification, then the [prescribed model label](intrinsic-model-parameters)
-    MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
-
--   Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
-    provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
-    of the model. In cases where [intrinsic](#paramdef-intrinsic) model parameters are all
-    contained within a single image file, field "`_parameter-`" nevertheless MUST be
-    included, with value "`all`"; e.g.:
+-   Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<param*>_model.nii[.gz]`"
+    provide data corresponding to the various requisite [model parameters](#paramdef-model). 
+    In cases where *all* [model parameters](#paramdef-model) are contained within a single image
+    file, field "`_parameter-`" nevertheless MUST be included, with value "`all`"; e.g.:
 
     ```Text
     <pipeline_name>/
         sub-<participant_label>/
             dwi/
-                <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
-                <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
+                <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_model.nii[.gz]
+                <source_keywords>[_space-<space>][_desc-<label>]_model.json
     ```
 
--   File "`<source_keywords>[_space-<space>][_desc-<label>]_<model>.json`"
-    provides basic model information and [input](#paramdef-input)
-    model parameters.
+-   File "`<source_keywords>[_space-<space>][_desc-<label>]_model.json`"
+    provides basic model information and [input parameters](#paramdef-input).
 
--   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.nii[.gz]`"
-    may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
-    model parameters.
+-   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<parama>_mdp.nii[.gz]`"
+    may be defined, in order to provide additional [model-derived parameters](#paramdef-derived).
 
--   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
-    may be defined to provide only information or parameters relevant to
-    derivation of each relevant [extrinsic](#paramdef-extrinsic) model
-    parameter image.
+-   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<param*>_mdp.json`"
+    may be defined to provide information or parameters only relevant to
+    each relevant [model-derived parameter](#paramdef-derived).
 
 ### Data representations
 
@@ -139,8 +132,8 @@ interpretation of that information; see [orientation specification](#orientation
 
 1.  <a name="data-scalar">*Scalars*</a>:
 
-    Any model parameter image (whether [intrinsic](#paramdef-intrinsic) or
-    [extrinsic](#paramdef-extrinsic)) where a solitary numerical value is
+    Any parameter image (whether [model](#paramdef-model) or
+    [model-derived](#paramdef-derived)) where a solitary numerical value is
     defined in each 3D image voxel is referred to here as a "scalar" image.
 
 1.  <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
@@ -201,8 +194,8 @@ interpretation of that information; see [orientation specification](#orientation
 
         Each 3-vector, once explicitly normalized, provides a direction
         on the unit sphere; the *norm* of each 3-vector additionally encodes
-        the magnitude of some model parameter, the nature of which MUST be
-        indicated in the "`_parameter-*`" filename field.
+        the magnitude of some model or model-derived parameter, the nature of
+        which MUST be indicated in the "`_parameter-*`" filename field.
 
     1.  Directions only
 
@@ -237,15 +230,14 @@ interpretation of that information; see [orientation specification](#orientation
 
     4D image containing, for every image voxel, data corresponding to some
     set of model parameters, the names and order of which are defined within
-    the [intrinsic](#paramdef-intrinsic) model parameters section.
+    the [model parameters](#paramdef-model) section below.
 
-### Intrinsic model parameters
+### Model parameters
 
-The following models are codified within the specification, and the model
-label should be used as the final field in the filename for storage of any
-intrinsic or extrinsic parameters. 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 future version of the specification.
+The following models are codified within the specification. The model label
+should be included in the "`_desc-`" field in the filename for storage
+of both model and model-derived parameters. Some models necessitate reserved
+keywords for "`_parameter-`" fields, which are listed below.
 
 | Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                        |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -319,7 +311,7 @@ Reserved keywords for models built into the specification are as follows:
 
     -   `RESTORESigma`: Float
 
-### Extrinsic model parameters
+### Model-derived parameters
 
 | `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources | Unit or scale                                                  |
 | ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------------------------- |
@@ -435,11 +427,15 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_dti.nii.gz
-                sub-01_dti.json
+                sub-01_desc-dti_parameter-all_model.nii.gz
+                sub-01_desc-dti_parameter-bzero_model.nii.gz
+                sub-01_desc-dti_parameter-fa_mdp.nii.gz
+                sub-01_desc-dti_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_desc-dti_parameter-all_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_desc-dti_parameter-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-dti_parameter-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
 
     Contents of JSON file:
 
@@ -461,20 +457,20 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-wm_csd.nii.gz
-                sub-01_desc-wm_csd.json
-                sub-01_desc-gm_csd.nii.gz
-                sub-01_desc-gm_csd.json
-                sub-01_desc-csf_csd.nii.gz
-                sub-01_desc-csf_csd.json
-                sub-01_csd.json
+                sub-01_desc-csd_parameter-wm_model.nii.gz
+                sub-01_desc-csd_parameter-wm_model.json
+                sub-01_desc-csd_parameter-gm_model.nii.gz
+                sub-01_desc-csd_parameter-gm_model.json
+                sub-01_desc-csd_parameter-csf_model.nii.gz
+                sub-01_desc-csd_parameter-csf_model.json
+                sub-01_desc-csd_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_desc-csd_parameter-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_desc-csd_parameter-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_desc-csd_parameter-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
-    Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
+    Contents of file "`sub-01_desc-csd_model.json`" (common to all [model parameters](#paramdef-model)):
 
     ```JSON
     {
@@ -488,7 +484,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-wm_csd.json`":
+    Contents of JSON file "`sub-01_desc-csd_parameter-wm_model.json`":
 
     ```JSON
     {
@@ -503,7 +499,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-gm_csd.json`":
+    Contents of JSON file "`sub-01_desc-csd_parameter_gm_model.json`":
 
     ```JSON
     {
@@ -525,24 +521,27 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-mean_parameter-bzero_bs.nii.gz
-                sub-01_desc-mean_parameter-dmean_bs.nii.gz
-                sub-01_desc-mean_parameter-dstd_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.json
-                sub-01_desc-merged_parameter-sticks_bs.nii.gz
-                sub-01_desc-merged_parameter-sticks_bs.json
-                sub-01_bs.json
+                sub-01_desc-bs_parameter-bzero_model.nii.gz
+                sub-01_desc-bs_parameter-bzero_model.json
+                sub-01_desc-bs_parameter-md_mdp.nii.gz
+                sub-01_desc-bs_parameter-md_mdp.json
+                sub-01_desc-bs_parameter-stdd_mdp.nii.gz
+                sub-01_desc-bs_parameter-stdd_mdp.json
+                sub-01_desc-bs_parameter-sticks_mdp.nii.gz
+                sub-01_desc-bs_parameter-sticks_mdp.json
+                sub-01_desc-bs_parameter-sticks_model.nii.gz
+                sub-01_desc-bs_parameter-sticks_model.json
+                sub-01_desc-bs_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+    Dimensions of NIfTI image "`sub-01_desc-bs_parameter-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-bs_parameter-ms_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-bs_parameter-stdd_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-bs_parameter-sticks_mdp.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_desc-bs_parameter-sticks_model.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
 
-    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
-    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
+    Contents of JSON files "`sub-01_desc-bs_parameter-sticks_mdp.json`"
+    and "`sub-01_desc-bs_parameter-sticks_model.json`" (contents of two
     files are identical):
 
     ```JSON
@@ -552,7 +551,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_bs.json`":
+    Contents of JSON file "`sub-01_desc-bs_model.json`":
 
     ```JSON
     {

From 618ee5bede48651ff1a5ce565855201608605843 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 2 Dec 2021 16:12:55 +1100
Subject: [PATCH 31/65] BEP016: Rename "dti" to "tensor"

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 5b28531a..f6b3cd8e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -96,7 +96,7 @@ rather than the image data).
 -   Field "`<model>`" is a unique identifier corresponding to the particular
     diffusion model. If the particular diffusion model is one that is included
     in this specification, then the [prescribed model label](intrinsic-model-parameters)
-    MUST be utilised; e.g. "`dti`" for the diffusion tensor model.
+    MUST be utilised; e.g. "`tensor`" for the diffusion tensor model.
 
 -   Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
     provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
@@ -251,7 +251,7 @@ ideally be integrated in a future version of the specification.
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
-| `dti`       | Diffusion Tensor Imaging \[[Basser1994](#basser1994)\]                                                                                          | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
+| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:
@@ -315,7 +315,7 @@ Reserved keywords for models built into the specification are as follows:
 
     -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
 
--   `dti` :
+-   `tensor` :
 
     -   `RESTORESigma`: Float
 
@@ -323,19 +323,19 @@ Reserved keywords for models built into the specification are as follows:
 
 | `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources | Unit or scale                                                  |
 | ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------------------------- |
-| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
 | `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#data-scalar)                       | { `csd` }              | Unitless                                                       |
-| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
-| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
-| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
-| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `dti` }              | Proportion \[0.0-1.0\]                                         |
+| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
+| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
+| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
+| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `tensor` }           | Proportion \[0.0-1.0\]                                         |
 | `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#data-scalar)                       | { `bs` }               | Volume fraction \[0.0-1.0\]                                    |
 | `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#data-scalar)                       | { `csd` }              | Proportion \[0.0-1.0\]                                         |
-| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `dti` }              |                                                                |
+| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
 | `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#data-3vector)                   | { `csd` }              | Same units as ODF                                              |
-| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `dti` }              | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
 
 While not explicitly included in the table above, *any* [scalar](#data-scalar)
 [extrinsic](paramdef-extrinsic) parameter can theoretically be combined
@@ -435,11 +435,11 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_dti.nii.gz
-                sub-01_dti.json
+                sub-01_tensor.nii.gz
+                sub-01_tensor.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_dti.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_tensor.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
 
     Contents of JSON file:
 

From 4e03dc7055e1bd54f2ed085794ed1d203dbd5ff9 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 9 Aug 2022 15:30:01 +1000
Subject: [PATCH 32/65] Rename "_parameter-" entity to "_param-"

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 3d019ff8..54133e26 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -83,14 +83,14 @@ rather than the image data).
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam1>_<model>.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam2>_<model>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_param-<intparam1>_<model>.nii[.gz]
+            <source_keywords>[_space-<space>][_desc-<label>]_param-<intparam2>_<model>.nii[.gz]
             <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
 
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam1>_<model>.json]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam2>_<model>.json]
+            [<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam1>_<model>.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam1>_<model>.json]
+            [<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam2>_<model>.nii[.gz]]
+            [<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam2>_<model>.json]
 ```
 
 -   Field "`<model>`" is a unique identifier corresponding to the particular
@@ -98,17 +98,17 @@ rather than the image data).
     in this specification, then the [prescribed model label](intrinsic-model-parameters)
     MUST be utilised; e.g. "`tensor`" for the diffusion tensor model.
 
--   Files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<intparam*>_<model>.nii[.gz]`"
+-   Files "`<source_keywords>[_space-<space>][_desc-<label>]_param-<intparam*>_<model>.nii[.gz]`"
     provide data corresponding to the various [intrinsic](#paramdef-intrinsic) parameters
     of the model. In cases where [intrinsic](#paramdef-intrinsic) model parameters are all
-    contained within a single image file, field "`_parameter-`" nevertheless MUST be
+    contained within a single image file, field "`_param-`" nevertheless MUST be
     included, with value "`all`"; e.g.:
 
     ```Text
     <pipeline_name>/
         sub-<participant_label>/
             dwi/
-                <source_keywords>[_space-<space>][_desc-<label>]_parameter-all_<model>.nii[.gz]
+                <source_keywords>[_space-<space>][_desc-<label>]_param-all_<model>.nii[.gz]
                 <source_keywords>[_space-<space>][_desc-<label>]_<model>.json
     ```
 
@@ -116,11 +116,11 @@ rather than the image data).
     provides basic model information and [input](#paramdef-input)
     model parameters.
 
--   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.nii[.gz]`"
+-   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam*>_<model>.nii[.gz]`"
     may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
     model parameters.
 
--   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_parameter-<extparam*>_<model>.json`"
+-   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_param-<extparam*>_<model>.json`"
     may be defined to provide only information or parameters relevant to
     derivation of each relevant [extrinsic](#paramdef-extrinsic) model
     parameter image.
@@ -165,7 +165,7 @@ interpretation of that information; see [orientation specification](#orientation
         and reference frame for angles:
 
         1.  Distance from origin; value of embedded parameter MUST be
-            indicated in "`_parameter-*`" filename field;
+            indicated in "`_param-*`" filename field;
 
         1.  Inclination / polar angle, in radians, relative to the zenith
             direction being the positive direction of the *third* reference
@@ -202,7 +202,7 @@ interpretation of that information; see [orientation specification](#orientation
         Each 3-vector, once explicitly normalized, provides a direction
         on the unit sphere; the *norm* of each 3-vector additionally encodes
         the magnitude of some model parameter, the nature of which MUST be
-        indicated in the "`_parameter-*`" filename field.
+        indicated in the "`_param-*`" filename field.
 
     1.  Directions only
 
@@ -450,7 +450,7 @@ another.
         "ReferenceAxes": "xyz",
         "Parameters": {
             "FitMethod": "ols",
-            "OutlierRejection": False
+            "OutlierRejection": false
         }
     }
     ```
@@ -525,24 +525,24 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-mean_parameter-bzero_bs.nii.gz
-                sub-01_desc-mean_parameter-dmean_bs.nii.gz
-                sub-01_desc-mean_parameter-dstd_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.nii.gz
-                sub-01_desc-mean_parameter-sticks_bs.json
-                sub-01_desc-merged_parameter-sticks_bs.nii.gz
-                sub-01_desc-merged_parameter-sticks_bs.json
+                sub-01_desc-mean_param-bzero_bs.nii.gz
+                sub-01_desc-mean_param-dmean_bs.nii.gz
+                sub-01_desc-mean_param-dstd_bs.nii.gz
+                sub-01_desc-mean_param-sticks_bs.nii.gz
+                sub-01_desc-mean_param-sticks_bs.json
+                sub-01_desc-merged_param-sticks_bs.nii.gz
+                sub-01_desc-merged_param-sticks_bs.json
                 sub-01_bs.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-mean_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_desc-merged_parameter-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+    Dimensions of NIfTI image "`sub-01_desc-mean_param-bzero_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_param-dmean_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_param-dstd_bs.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_desc-mean_param-sticks_bs.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_desc-merged_param-sticks_bs.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
 
-    Contents of JSON files "`sub-01_desc-mean_parameter-sticks_bs.json`"
-    and "`sub-01_desc-merged_parameter-sticks_bs.json`" (contents of two
+    Contents of JSON files "`sub-01_desc-mean_param-sticks_bs.json`"
+    and "`sub-01_desc-merged_param-sticks_bs.json`" (contents of two
     files are identical):
 
     ```JSON

From a83d6072a4b517c30fc5659f28c996db8c114cb9 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 9 Aug 2022 15:38:20 +1000
Subject: [PATCH 33/65] DWI derivatives: Compulsory "parameter" entity

While the specification states that the "parameter" entity must always be defined---even if all model parameters are encoded within a single image, in which case value "all" must be used---two of the demonstrative examples did not obey such.
---
 .../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 3d019ff8..1fc75d5d 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -435,11 +435,11 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_tensor.nii.gz
+                sub-01_parameter-all_tensor.nii.gz
                 sub-01_tensor.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_tensor.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_parameter-all_tensor.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
 
     Contents of JSON file:
 
@@ -450,7 +450,7 @@ another.
         "ReferenceAxes": "xyz",
         "Parameters": {
             "FitMethod": "ols",
-            "OutlierRejection": False
+            "OutlierRejection": false
         }
     }
     ```
@@ -461,18 +461,18 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-wm_csd.nii.gz
-                sub-01_desc-wm_csd.json
-                sub-01_desc-gm_csd.nii.gz
-                sub-01_desc-gm_csd.json
-                sub-01_desc-csf_csd.nii.gz
-                sub-01_desc-csf_csd.json
+                sub-01_parameter-wm_csd.nii.gz
+                sub-01_parameter-wm_csd.json
+                sub-01_parameter-gm_csd.nii.gz
+                sub-01_parameter-gm_csd.json
+                sub-01_parameter-csf_csd.nii.gz
+                sub-01_parameter-csf_csd.json
                 sub-01_csd.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_parameter-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_parameter-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_parameter-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
     Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
 
@@ -488,7 +488,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-wm_csd.json`":
+    Contents of JSON file "`sub-01_parameter-wm_csd.json`":
 
     ```JSON
     {
@@ -503,7 +503,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-gm_csd.json`":
+    Contents of JSON file "`sub-01_parameter-gm_csd.json`":
 
     ```JSON
     {

From c7cfbafb7d0269eab621c928f7f779183cc9243b Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 10 Aug 2022 19:42:06 +1000
Subject: [PATCH 34/65] DWI derivatives: Resolution between content changes

Resolves bids-standard/bids-bep016#52 (making "parameter" entity compulsory) against bids-standard/bids-bep016#51 (changing key for that parameter from "parameter" to "param").
---
 .../05-diffusion-derivatives.md               | 26 +++++++++----------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index cf476c8f..62e5a77d 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -435,11 +435,11 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_parameter-all_tensor.nii.gz
+                sub-01_param-all_tensor.nii.gz
                 sub-01_tensor.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_parameter-all_tensor.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_param-all_tensor.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
 
     Contents of JSON file:
 
@@ -461,18 +461,18 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_parameter-wm_csd.nii.gz
-                sub-01_parameter-wm_csd.json
-                sub-01_parameter-gm_csd.nii.gz
-                sub-01_parameter-gm_csd.json
-                sub-01_parameter-csf_csd.nii.gz
-                sub-01_parameter-csf_csd.json
+                sub-01_param-wm_csd.nii.gz
+                sub-01_param-wm_csd.json
+                sub-01_param-gm_csd.nii.gz
+                sub-01_param-gm_csd.json
+                sub-01_param-csf_csd.nii.gz
+                sub-01_param-csf_csd.json
                 sub-01_csd.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_parameter-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_parameter-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_parameter-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_param-wm_csd.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_param-gm_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_param-csf_csd.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
     Contents of file "`sub-01_csd.json`" (common to all [intrinsic](#paramdef-intrinsic) model parameter images):
 
@@ -488,7 +488,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_parameter-wm_csd.json`":
+    Contents of JSON file "`sub-01_param-wm_csd.json`":
 
     ```JSON
     {
@@ -503,7 +503,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_parameter-gm_csd.json`":
+    Contents of JSON file "`sub-01_param-gm_csd.json`":
 
     ```JSON
     {

From d3bbb8686a3b4c6298bcee29f4df51e199dfc720 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 16 Aug 2022 15:40:30 +1000
Subject: [PATCH 35/65] DWI derivatives: Fix tensor model example

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index ccd1c3f6..a6847f5f 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -83,7 +83,6 @@ rather than the image data).
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-<<<<<<< HEAD
             <source_keywords>[_space-<space>][_desc-<label>]_param-<param1>_model.nii[.gz]
             <source_keywords>[_space-<space>][_desc-<label>]_param-<param1>_model.json
             <source_keywords>[_space-<space>][_desc-<label>]_param-<param2>_model.nii[.gz]
@@ -428,13 +427,13 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-dti_param-all_model.nii.gz
+                sub-01_desc-dti_param-tensor_model.nii.gz
                 sub-01_desc-dti_param-bzero_model.nii.gz
                 sub-01_desc-dti_param-fa_mdp.nii.gz
                 sub-01_desc-dti_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-dti_param-all_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_desc-dti_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
     Dimensions of NIfTI image "`sub-01_desc-dti_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
     Dimensions of NIfTI image "`sub-01_desc-dti_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
 

From d86b7cdc35e4de68071f7a6e56741b23873f30f1 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 16 Aug 2022 15:56:44 +1000
Subject: [PATCH 36/65] DWI derivatives: "model" as entity

---
 .../05-diffusion-derivatives.md               | 139 +++++++++---------
 1 file changed, 70 insertions(+), 69 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index a6847f5f..d887d827 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -83,38 +83,39 @@ rather than the image data).
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>][_desc-<label>]_param-<param1>_model.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_param-<param1>_model.json
-            <source_keywords>[_space-<space>][_desc-<label>]_param-<param2>_model.nii[.gz]
-            <source_keywords>[_space-<space>][_desc-<label>]_param-<param2>_model.json
-            <source_keywords>[_space-<space>][_desc-<label>]_model.json
-
-            [<source_keywords>[_space-<space>][_desc-<label>]_param-<parama>_mdp.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_param-<parama>_mdp.json]
-            [<source_keywords>[_space-<space>][_desc-<label>]_param-<paramb>_mdp.nii[.gz]]
-            [<source_keywords>[_space-<space>][_desc-<label>]_param-<paramb>_mdp.json]
+            <source_keywords>[_space-<space>]_model-<label>_param-<param1>_model.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>_param-<param1>_model.json
+            <source_keywords>[_space-<space>]_model-<label>_param-<param2>_model.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>_param-<param2>_model.json
+            <source_keywords>[_space-<space>]_model-<label>_model.json
+
+            [<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.nii[.gz]]
+            [<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.json]
+            [<source_keywords>[_space-<space>]_model-<label>_param-<paramb>_mdp.nii[.gz]]
+            [<source_keywords>[_space-<space>]_model-<label>_param-<paramb>_mdp.json]
 ```
 
--   Files "`<source_keywords>[_space-<space>][_desc-<label>]_param-<param*>_model.nii[.gz]`"
+-   Files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_model.nii[.gz]`"
     provide data corresponding to the various requisite [model parameters](#paramdef-model). 
-    In cases where *all* [model parameters](#paramdef-model) are contained within a single image
-    file, field "`_parameter-`" nevertheless MUST be included, with value "`all`"; e.g.:
-
-    ```Text
-    <pipeline_name>/
-        sub-<participant_label>/
-            dwi/
-                <source_keywords>[_space-<space>][_desc-<label>]_param-all_model.nii[.gz]
-                <source_keywords>[_space-<space>][_desc-<label>]_model.json
-    ```
-
--   File "`<source_keywords>[_space-<space>][_desc-<label>]_model.json`"
+    
+    -   In cases where *all* [model parameters](#paramdef-model) are contained within a single image
+        file, field "`_parameter-`" nevertheless MUST be included, with value "`all`"; e.g.:
+
+        ```Text
+        <pipeline_name>/
+            sub-<participant_label>/
+                dwi/
+                    <source_keywords>[_space-<space>]_model-<label>_param-all_model.nii[.gz]
+                    <source_keywords>[_space-<space>]_model-<label>_model.json
+        ```
+
+-   File "`<source_keywords>[_space-<space>]_model-<label>_model.json`"
     provides basic model information and [input parameters](#paramdef-input).
 
--   OPTIONAL images "`<source_keywords>[_space-<space>][_desc-<label>]_param-<parama>_mdp.nii[.gz]`"
+-   OPTIONAL images "`<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.nii[.gz]`"
     may be defined, in order to provide additional [model-derived parameters](#paramdef-derived).
 
--   OPTIONAL files "`<source_keywords>[_space-<space>][_desc-<label>]_param-<param*>_mdp.json`"
+-   OPTIONAL files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_mdp.json`"
     may be defined to provide information or parameters only relevant to
     each relevant [model-derived parameter](#paramdef-derived).
 
@@ -158,7 +159,7 @@ interpretation of that information; see [orientation specification](#orientation
         and reference frame for angles:
 
         1.  Distance from origin; value of embedded parameter MUST be
-            indicated in "`_param-*`" filename field;
+            indicated in "`_param-*`" entity;
 
         1.  Inclination / polar angle, in radians, relative to the zenith
             direction being the positive direction of the *third* reference
@@ -195,7 +196,7 @@ interpretation of that information; see [orientation specification](#orientation
         Each 3-vector, once explicitly normalized, provides a direction
         on the unit sphere; the *norm* of each 3-vector additionally encodes
         the magnitude of some model or model-derived parameter, the nature of
-        which MUST be indicated in the "`_param-*`" filename field.
+        which MUST be indicated in the "`_param-*`" entity.
 
     1.  Directions only
 
@@ -235,14 +236,14 @@ interpretation of that information; see [orientation specification](#orientation
 ### Model parameters
 
 The following models are codified within the specification. The model label
-should be included in the "`_desc-`" field in the filename for storage
+should be included in the "`_model-`" entity in the filename for storage
 of both model and model-derived parameters. Some models necessitate reserved
-keywords for "`_parameter-`" fields, which are listed below.
+keywords for "`_param-`" fields, which are listed below.
 
 | Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                        |
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
-| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_desc-<desc>`" filename field being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
+| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_param-<param>`" entity being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
 | `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
@@ -427,15 +428,15 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-dti_param-tensor_model.nii.gz
-                sub-01_desc-dti_param-bzero_model.nii.gz
-                sub-01_desc-dti_param-fa_mdp.nii.gz
-                sub-01_desc-dti_model.json
+                sub-01_model-dti_param-tensor_model.nii.gz
+                sub-01_model-dti_param-bzero_model.nii.gz
+                sub-01_model-dti_param-fa_mdp.nii.gz
+                sub-01_model-dti_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-dti_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
-    Dimensions of NIfTI image "`sub-01_desc-dti_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-dti_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-dti_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_model-dti_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-dti_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
 
     Contents of JSON file:
 
@@ -457,20 +458,20 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-csd_param-wm_model.nii.gz
-                sub-01_desc-csd_param-wm_model.json
-                sub-01_desc-csd_param-gm_model.nii.gz
-                sub-01_desc-csd_param-gm_model.json
-                sub-01_desc-csd_param-csf_model.nii.gz
-                sub-01_desc-csd_param-csf_model.json
-                sub-01_desc-csd_model.json
+                sub-01_model-csd_param-wm_model.nii.gz
+                sub-01_model-csd_param-wm_model.json
+                sub-01_model-csd_param-gm_model.nii.gz
+                sub-01_model-csd_param-gm_model.json
+                sub-01_model-csd_param-csf_model.nii.gz
+                sub-01_model-csd_param-csf_model.json
+                sub-01_model-csd_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_desc-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
+    Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
-    Contents of file "`sub-01_desc-csd_model.json`" (common to all [model parameters](#paramdef-model)):
+    Contents of file "`sub-01_model-csd_model.json`" (common to all [model parameters](#paramdef-model)):
 
     ```JSON
     {
@@ -484,7 +485,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-csd_param-wm_model.json`":
+    Contents of JSON file "`sub-01_model-csd_param-wm_model.json`":
 
     ```JSON
     {
@@ -499,7 +500,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-csd_param_gm_model.json`":
+    Contents of JSON file "`sub-01_model-csd_param_gm_model.json`":
 
     ```JSON
     {
@@ -521,27 +522,27 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_desc-bs_param-bzero_model.nii.gz
-                sub-01_desc-bs_param-bzero_model.json
-                sub-01_desc-bs_param-md_mdp.nii.gz
-                sub-01_desc-bs_param-md_mdp.json
-                sub-01_desc-bs_param-stdd_mdp.nii.gz
-                sub-01_desc-bs_param-stdd_mdp.json
-                sub-01_desc-bs_param-sticks_mdp.nii.gz
-                sub-01_desc-bs_param-sticks_mdp.json
-                sub-01_desc-bs_param-sticks_model.nii.gz
-                sub-01_desc-bs_param-sticks_model.json
-                sub-01_desc-bs_model.json
+                sub-01_model-bs_param-bzero_model.nii.gz
+                sub-01_model-bs_param-bzero_model.json
+                sub-01_model-bs_param-md_mdp.nii.gz
+                sub-01_model-bs_param-md_mdp.json
+                sub-01_model-bs_param-stdd_mdp.nii.gz
+                sub-01_model-bs_param-stdd_mdp.json
+                sub-01_model-bs_param-sticks_mdp.nii.gz
+                sub-01_model-bs_param-sticks_mdp.json
+                sub-01_model-bs_param-sticks_model.nii.gz
+                sub-01_model-bs_param-sticks_model.json
+                sub-01_model-bs_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_desc-bs_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-bs_param-ms_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-bs_param-stdd_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_desc-bs_param-sticks_mdp.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_desc-bs_param-sticks_model.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
+    Dimensions of NIfTI image "`sub-01_model-bs_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_param-ms_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_param-stdd_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_param-sticks_mdp.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
+    Dimensions of NIfTI image "`sub-01_model-bs_param-sticks_model.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
 
-    Contents of JSON files "`sub-01_desc-bs_param-sticks_mdp.json`"
-    and "`sub-01_desc-bs_param-sticks_model.json`" (contents of two
+    Contents of JSON files "`sub-01_model-bs_param-sticks_mdp.json`"
+    and "`sub-01_model-bs_param-sticks_model.json`" (contents of two
     files are identical):
 
     ```JSON
@@ -551,7 +552,7 @@ another.
     }
     ```
 
-    Contents of JSON file "`sub-01_desc-bs_model.json`":
+    Contents of JSON file "`sub-01_model-bs_model.json`":
 
     ```JSON
     {

From a4532747c2c02d1c1f895e2f908fb3702af48f09 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 12 Sep 2022 16:26:14 -0500
Subject: [PATCH 37/65] DWI models: Restore renaming "dti" to "tensor"

Changes in #47 were lost in the process of conflict merging.
---
 src/05-derivatives/05-diffusion-derivatives.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 69672d41..8821f41c 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -104,6 +104,7 @@ rather than the image data).
             sub-<participant_label>/
                 dwi/
                     <source_keywords>[_space-<space>]_model-<label>_param-all_model.nii[.gz]
+                    [<source_keywords>[_space-<space>]_model-<label>_param-all_model.json]
                     <source_keywords>[_space-<space>]_model-<label>_model.json
         ```
 
@@ -426,15 +427,15 @@ another.
     my_diffusion_pipeline/
         sub-01/
             dwi/
-                sub-01_model-dti_param-tensor_model.nii.gz
-                sub-01_model-dti_param-bzero_model.nii.gz
-                sub-01_model-dti_param-fa_mdp.nii.gz
-                sub-01_model-dti_model.json
+                sub-01_model-tensor_param-tensor_model.nii.gz
+                sub-01_model-tensor_param-bzero_model.nii.gz
+                sub-01_model-tensor_param-fa_mdp.nii.gz
+                sub-01_model-tensor_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_model-dti_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
-    Dimensions of NIfTI image "`sub-01_model-dti_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_model-dti_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
 
     Contents of JSON file:
 

From 4746056d73bc6fa44b262815ab348785cc447265 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 13 Sep 2022 15:35:09 -0500
Subject: [PATCH 38/65] BEP016: Remove reference to old terminology

Formerly known as "intrinsic" model parameters are now (currently) referred to as simply "model parameters".
---
 src/05-derivatives/05-diffusion-derivatives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 69672d41..ea3443a5 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -67,7 +67,7 @@ these uses is defined thus:
 1.  <a name="paramdef-derived">Model-*derived*</a> parameter:
 
     Value that can be calculated directly from previously estimated
-    intrinsic model parameters, without necessitating reference to
+    *model parameters*, without necessitating reference to
     the empirical diffusion-weighted data.
 
 For example, consider a diffusion tensor model fit: the number of

From c13031eb60697f90c331370d38701c6b0762dc97 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 13 Sep 2022 15:39:56 -0500
Subject: [PATCH 39/65] BEP016: Revert "_param-all"

In cases where all model parameters can be encapsulated in a single NIfTI image, revert back to the case where the "param" entity is omitted from the file name.
Reverts https://github.com/bids-standard/bids-bep016/pull/52.
---
 src/05-derivatives/05-diffusion-derivatives.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 8821f41c..d3343bf9 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -97,14 +97,14 @@ rather than the image data).
 
 -   Files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_model.nii[.gz]`"
     provide data corresponding to the various requisite [model parameters](#paramdef-model).
+
     In cases where *all* [model parameters](#paramdef-model) are contained within a single image
-    file, entity "`_param-`" nevertheless MUST be included, with value "`all`"; e.g.:
+    file, entity "`_param-`" MUST NOT be included; e.g.:
         ```Text
         <pipeline_name>/
             sub-<participant_label>/
                 dwi/
-                    <source_keywords>[_space-<space>]_model-<label>_param-all_model.nii[.gz]
-                    [<source_keywords>[_space-<space>]_model-<label>_param-all_model.json]
+                    <source_keywords>[_space-<space>]_model-<label>_model.nii[.gz]
                     <source_keywords>[_space-<space>]_model-<label>_model.json
         ```
 
@@ -243,7 +243,7 @@ keywords for "`_param-`" fields, which are listed below.
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_param-<param>`" entity being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
-| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [parameter vectors](#data-param) image with parameter name "`all`" with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
+| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [parameter vectors](#data-param) image with no `param` entity with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:

From 4489a0c8d01c01603689904bde5247d14b956298 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 13 Sep 2022 15:54:55 -0500
Subject: [PATCH 40/65] BEP016: Adopt "model fit parameters" terminology

In order to better disambiguate the various types of "parameters" defined, change "model parameters" to "model fit parameters".
---
 .../05-diffusion-derivatives.md               | 23 ++++++++++---------
 1 file changed, 12 insertions(+), 11 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 0b4b0427..9a2836e3 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -37,11 +37,12 @@ biological structure. A wide range of such models are available, each of
 which has its own unique requirements with respect to:
 
 -   The [input](#paramdef-input) parameters required in order to
-    define / constrain the model;
+    define / constrain the way in which the model will be fit to the
+    empirical image data;
 
 -   The appropriate [data representations](#data-representations) utilised to
-    store information parameterised [by](#paramdef-intrinsic) or
-    [from](#paramdef-extrinsic) the model onto the filesystem;
+    store information parameterised [by](#paramdef-fit) or
+    [from](#paramdef-derived) the model onto the filesystem;
 
 -   The requirements for encapsulation and complete representation of
     derived [orientation information](#orientation-specification), which is
@@ -59,7 +60,7 @@ these uses is defined thus:
     Value or non-numerical setting that influences the conformation
     of the diffusion model to the empirical diffusion-weighted data.
 
-1.  <a name="paramdef-model">*Model*</a> parameter:
+1.  <a name="paramdef-fit">Model *fit*</a> parameter:
 
     Value that is the direct result of fitting the diffusion model to the
     empirical diffusion-weighted data.
@@ -72,7 +73,7 @@ these uses is defined thus:
 
 For example, consider a diffusion tensor model fit: the number of
 iterations in the optimisation algorithm would be an *input* parameter;
-the six unique diffusion tensor coefficients would be the *model*
+the six unique diffusion tensor coefficients would be the *model fit*
 parameters; the Fractional Anisotropy (FA) would be a *model-derived*
 parameter (as it is calculated from the diffusion tensor coefficients
 rather than the image data).
@@ -96,9 +97,9 @@ rather than the image data).
 ```
 
 -   Files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_model.nii[.gz]`"
-    provide data corresponding to the various requisite [model parameters](#paramdef-model).
+    provide data corresponding to the various requisite [model fit parameters](#paramdef-fit).
 
-    In cases where *all* [model parameters](#paramdef-model) are contained within a single image
+    In cases where *all* [model fit parameters](#paramdef-fit) are contained within a single image
     file, entity "`_param-`" MUST NOT be included; e.g.:
         ```Text
         <pipeline_name>/
@@ -132,7 +133,7 @@ interpretation of that information; see [orientation specification](#orientation
 
 1.  <a name="data-scalar">*Scalars*</a>:
 
-    Any parameter image (whether [model](#paramdef-model) or
+    Any parameter image (whether [model fit](#paramdef-fit) or
     [model-derived](#paramdef-derived)) where a solitary numerical value is
     defined in each 3D image voxel is referred to here as a "scalar" image.
 
@@ -230,7 +231,7 @@ interpretation of that information; see [orientation specification](#orientation
 
     4D image containing, for every image voxel, data corresponding to some
     set of model parameters, the names and order of which are defined within
-    the [model parameters](#paramdef-model) section below.
+    the [model fit parameters](#paramdef-fit) section below.
 
 ### Model parameters
 
@@ -330,7 +331,7 @@ Reserved keywords for models built into the specification are as follows:
 | `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
 
 While not explicitly included in the table above, *any* [scalar](#data-scalar)
-[extrinsic](paramdef-extrinsic) parameter can theoretically be combined
+[model-derived parameter](paramdef-derived) can theoretically be combined
 with a separate source of orientation information from the diffusion model
 in order to produce a [directionally-encoded colour](#data-dec),
 [spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
@@ -470,7 +471,7 @@ another.
     Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
     Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
 
-    Contents of file "`sub-01_model-csd_model.json`" (common to all [model parameters](#paramdef-model)):
+    Contents of file "`sub-01_model-csd_model.json`" (common to all [model fit parameters](#paramdef-fit)):
 
     ```JSON
     {

From f4a7239dd2218513f9f079c1ff619429a289c5e3 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 13 Sep 2022 16:00:22 -0500
Subject: [PATCH 41/65] BEP016: Remove references to removed "pdf" data
 representation

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 0b4b0427..d4207c03 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -337,15 +337,15 @@ in order to produce a [directionally-encoded colour](#data-dec),
 
 ### Orientation specification
 
-| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                                                                        | **Description**                                                                                                                                                                                                                                           |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [probability distribution functions](#data-pdf), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
-| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                                                                           | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
-| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                                                                              | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
-| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `pdf`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.         |
-| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                                                                 | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. String; allowed values: { `MRtrix3` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                          |
-| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                                                                   | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
+| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                       | **Description**                                                                                                                                                                                                                                           |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
+| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                          | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
+| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
+| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.                |
+| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                |
+| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                  | REQUIRED. String; allowed values: { `MRtrix3` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                          |
+| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                  | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
 
 If `AntipodalSymmetry` is True, then no constraints are imposed with respect
 to the domain on the 2-sphere in which orientations may be specified;

From eddad2289617ebaf20d43475dba2b299a41e0e50 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 7 Oct 2022 12:41:26 +1100
Subject: [PATCH 42/65] DWI derivatives: Make tensor a data representation

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

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index f3e0813f..44d7b566 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -144,6 +144,18 @@ interpretation of that information; see [orientation specification](#orientation
     \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
     values.
 
+1.  <a name="data-tensor">*Rank-2 tensor*</a>:
+
+    4D image encoding coefficients of a rank-2 tensor.
+    If `"AntipodalSymmetry"` is `True` (or omitted),
+    then the image MUST contain six volumes, in the order:
+    *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>.
+    If `"AntipodalSymmetry"` is `False`,
+    then the image MUST contain nine volumes, in the order:
+    *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yx</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>, *D<sub>zx</sub>*, *D<sub>zy</sub>*, *D<sub>zz</sub>.
+    (If `"ReferenceAxes"` is `"ijk"`, then the interpretation of the coefficients
+    above should be substituted accordingly)
+
 1.  <a name="data-spherical">*Spherical coordinates*</a>:
 
     4D image where data across volumes within each voxel encode one or
@@ -244,7 +256,7 @@ keywords for "`_param-`" fields, which are listed below.
 | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
 | `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_param-<param>`" entity being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
-| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [parameter vectors](#data-param) image with no `param` entity with 6 volumes in the order: *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>*<br>OR<br>Tensor coefficients as [parameter vectors](#data-param) image with parameter name "`tensor`";<br>Estimated *b*=0 intensity as [scalar](#data-scalar) image with parameter name "`bzero`" |
+| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [tensor image](#data-tensor) with no `param` entity <br>OR<br>Tensor coefficients as [tensor image](#data-tensor) image with `param` entity ``tensor``;<br>Estimated *b*=0 intensity as [scalar image](#data-scalar) with `param` entity "`bzero`" |
 
 The JSON sidecar for the intrinsic diffusion model parameters may contain
 the following key/value pairs irrespective of the particular model:
@@ -340,7 +352,7 @@ in order to produce a [directionally-encoded colour](#data-dec),
 
 | **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                       | **Description**                                                                                                                                                                                                                                           |
 | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AntipodalSymmetry`         | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
+| `AntipodalSymmetry`         | [Tensor](#data_tensor), [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
 | `Directions`                | [Amplitudes](#data-amp)                                                                                                                                          | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
 | `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
 | `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.                |
@@ -434,7 +446,7 @@ another.
                 sub-01_model-tensor_model.json
     ```
 
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([parameter vectors](#data-param))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([tensor image](#data-tensor))
     Dimensions of NIfTI image "`sub-01_model-tensor_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
     Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
 

From bcd768cbb40cff053e13625c90da5cd8172321fa Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 7 Oct 2022 13:00:04 +1100
Subject: [PATCH 43/65] DWI derivatives: Fix ModelDescription in exemplars

Specification requests field "ModelDescription", but exemplars at end of document instead erroneously used key "Model".
---
 src/05-derivatives/05-diffusion-derivatives.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index f3e0813f..47f6c456 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -442,7 +442,7 @@ another.
 
     ```JSON
     {
-        "Model": "Diffusion Tensor",
+        "ModelDescription": "Diffusion Tensor",
         "OrientationRepresentation": "param",
         "ReferenceAxes": "xyz",
         "Parameters": {
@@ -475,7 +475,7 @@ another.
 
     ```JSON
     {
-        "Model": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "ModelDescription": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
         "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
         "Shells": [ 0, 1000, 2000, 3000 ],
         "Parameters": {
@@ -556,7 +556,7 @@ another.
 
     ```JSON
     {
-        "Model": "Ball-And-Sticks model using FSL bedpostx",
+        "ModelDescription": "Ball-And-Sticks model using FSL bedpostx",
         "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
         "Parameters": {
             "ARDFudgeFactor": 1.0,

From 79947065dfdbe9fef5c31504c74af03846ceecaa Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Tue, 25 Apr 2023 09:49:19 -0700
Subject: [PATCH 44/65] Adds the descoteaux 2007 convention.

Based on https://github.com/dipy/dipy/blob/master/dipy/reconst/shm.py#L427-L430
---
 src/derivatives/05-diffusion-derivatives.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 47f6c456..fa36b913 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -370,8 +370,6 @@ another.
 
         for *maximum* spherical harmonic order *l<sub>max</sub>*.
 
--   `MRtrix3`
-
     -   Functions assumed to be real: conjugate symmetry is assumed, i.e.
         *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
         conjugate.
@@ -381,8 +379,14 @@ another.
 
     -   Utilised basis functions:
 
+        -   `MRtrix3`
+
         ![MRtrix3 SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
 
+        -   `Descoteaux`
+
+        ![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m%3C0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m%3E0\\&space;\end{Bmatrix})
+
     -   Mapping between image volume *V* and spherical harmonic basis
         function coefficient *Y<sub>l,m</sub>*:
 
@@ -420,6 +424,7 @@ another.
         | --------------------- |--:|--:|--:|--:|--:| :--: |
         | ***N***               | 1 | 2 | 3 | 4 | 5 | etc. |
 
+
 ## Demonstrative examples
 
 -   A basic Diffusion Tensor fit:

From 2fa59406483893fa95ec3d4503f39905b8858b99 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Fri, 28 Apr 2023 20:28:07 -0700
Subject: [PATCH 45/65] Change from strange html encoding to "<" and ">"

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fa36b913..87240914 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -385,7 +385,7 @@ another.
 
         -   `Descoteaux`
 
-        ![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m%3C0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m%3E0\\&space;\end{Bmatrix})
+        ![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
 
     -   Mapping between image volume *V* and spherical harmonic basis
         function coefficient *Y<sub>l,m</sub>*:

From dd8fe323b8a9cef65b11d76533c7e47514348c20 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Fri, 28 Apr 2023 20:41:25 -0700
Subject: [PATCH 46/65] Fix codespell-detected British spellings.

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 87240914..d4739f8d 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -40,7 +40,7 @@ which has its own unique requirements with respect to:
     define / constrain the way in which the model will be fit to the
     empirical image data;
 
--   The appropriate [data representations](#data-representations) utilised to
+-   The appropriate [data representations](#data-representations) utilized to
     store information parameterised [by](#paramdef-fit) or
     [from](#paramdef-derived) the model onto the filesystem;
 
@@ -72,7 +72,7 @@ these uses is defined thus:
     the empirical diffusion-weighted data.
 
 For example, consider a diffusion tensor model fit: the number of
-iterations in the optimisation algorithm would be an *input* parameter;
+iterations in the optimization algorithm would be an *input* parameter;
 the six unique diffusion tensor coefficients would be the *model fit*
 parameters; the Fractional Anisotropy (FA) would be a *model-derived*
 parameter (as it is calculated from the diffusion tensor coefficients
@@ -137,10 +137,10 @@ interpretation of that information; see [orientation specification](#orientation
     [model-derived](#paramdef-derived)) where a solitary numerical value is
     defined in each 3D image voxel is referred to here as a "scalar" image.
 
-1.  <a name="data-dec">*Directionally-Encoded Colours (DEC)*</a>:
+1.  <a name="data-dec">*Directionally-Encoded colors (DEC)*</a>:
 
     4D image with three volumes, intended to be interpreted as red, green
-    and blue colour intensities for visualisation
+    and blue color intensities for visualization
     \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
     values.
 
@@ -277,7 +277,7 @@ field depends on the particular model used.
 
 | **Key name**     | **Description**                                                                                                                                                                                                                                                                                        |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FitMethod        | OPTIONAL. String. The optimisation procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Options are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
+| FitMethod        | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Options are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
 | Iterations       | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                    |
 | OutlierRejection | OPTIONAL. Boolean. Value indicating whether or not rejection of outlier values was performed during fitting of the intrinsic model parameters.                                                                                                                                                         |
 | Samples          | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters are provided.                                                                                                                                  |
@@ -293,7 +293,7 @@ Reserved keywords for models built into the specification are as follows:
 
 -   `csd`:
 
-    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularisation ("`soft`") or prevention ("`hard`") of negative values.
+    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularization ("`soft`") or prevention ("`hard`") of negative values.
 
     -   `ResponseFunctionZSH`: Two options:
 
@@ -333,7 +333,7 @@ Reserved keywords for models built into the specification are as follows:
 While not explicitly included in the table above, *any* [scalar](#data-scalar)
 [model-derived parameter](paramdef-derived) can theoretically be combined
 with a separate source of orientation information from the diffusion model
-in order to produce a [directionally-encoded colour](#data-dec),
+in order to produce a [directionally-encoded color](#data-dec),
 [spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
 
 ### Orientation specification
@@ -377,7 +377,7 @@ another.
     -   Antipodally symmetric: all basis functions with odd degree are
         assumed zero; `AntipodalSymmetry` MUST NOT be set to `False`.
 
-    -   Utilised basis functions:
+    -   Utilized basis functions:
 
         -   `MRtrix3`
 
@@ -516,7 +516,7 @@ another.
                                  [ 224.9 ],
                                  [ 128.8 ] ],
         "SphericalHarmonicDegree": 0,
-        "Tissue": "Grey matter"
+        "Tissue": "Gray matter"
     }
     ```
 

From 7a605fd294c6b30b75bd0cc0ceb92c9feb893871 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Wed, 28 Jun 2023 07:22:46 -0700
Subject: [PATCH 47/65] Replace the latin "etc" with ellipses.

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index d4739f8d..4536907e 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -402,7 +402,7 @@ another.
         | 5       | *Y<sub>2,2</sub>*  |
         | 6       | *Y<sub>4,-4</sub>* |
         | 7       | *Y<sub>4,-3</sub>* |
-        | ...     | etc.               |
+        | ...     | ...                |
 
     -   Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
         and number of image volumes *N*:
@@ -411,7 +411,7 @@ another.
 
         | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | ...  |
         | --------------------- |--:|--:|--: |--: |--: | :--: |
-        | ***N***               | 1 | 6 | 15 | 28 | 45 | etc. |
+        | ***N***               | 1 | 6 | 15 | 28 | 45 | ...  |
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
@@ -422,7 +422,7 @@ another.
 
         | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | ...  |
         | --------------------- |--:|--:|--:|--:|--:| :--: |
-        | ***N***               | 1 | 2 | 3 | 4 | 5 | etc. |
+        | ***N***               | 1 | 2 | 3 | 4 | 5 | ...  |
 
 
 ## Demonstrative examples

From 0a04ee6b1c042ac2f12e694163992a0980e9419d Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Mon, 11 Sep 2023 07:13:54 +0000
Subject: [PATCH 48/65] Bump actions/checkout from 3 to 4

Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v3...v4)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/schemacode_ci.yml |  8 ++++----
 .github/workflows/validation.yml    | 10 +++++-----
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/schemacode_ci.yml b/.github/workflows/schemacode_ci.yml
index 8188370c..e888fb06 100644
--- a/.github/workflows/schemacode_ci.yml
+++ b/.github/workflows/schemacode_ci.yml
@@ -26,7 +26,7 @@ jobs:
         os: ["ubuntu-latest"]
         python-version: ["3.11"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
@@ -64,7 +64,7 @@ jobs:
             python-version: 3
     name: ${{ matrix.os }} with Python ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: "Set up Python"
         uses: actions/setup-python@v4
@@ -129,7 +129,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Validate schema
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set Up Python environment
         uses: actions/setup-python@v4
@@ -157,7 +157,7 @@ jobs:
     needs: [test, validate_schema]
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Download artifacts
         uses: actions/download-artifact@v3
diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml
index 91ba4d49..2bbc822c 100644
--- a/.github/workflows/validation.yml
+++ b/.github/workflows/validation.yml
@@ -16,14 +16,14 @@ jobs:
   codespell:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: codespell-project/actions-codespell@master
 
   # Markdown formatting
   remark:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
           node-version: 14
@@ -36,7 +36,7 @@ jobs:
   yamllint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3
@@ -49,7 +49,7 @@ jobs:
   python-style:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3
@@ -63,7 +63,7 @@ jobs:
   latin-phrases:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-python@v4
         with:
           python-version: 3

From c62a2d7df0b64f825bc1d2374ebbc3116ff84c01 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 26 Apr 2024 13:37:17 +1000
Subject: [PATCH 49/65] BEP016: Major changes

- Reject suffices "mfp" (or earlier "_model") / "mfp" in favour of "_dwimap". Instead adopt distinction of "model metadata" vs. "parameter metadata".
- Reject use of advanced inheritance in favour of listing all relevant metadata for each data file in the sidecar JSON.
- Greater use of sub-dictionaries in JSON files to assist in separating metadata relevant to a model as a whole vs. only that particular parameter of the model.
---
 src/derivatives/05-diffusion-derivatives.md | 1166 ++++++++++++-------
 1 file changed, 723 insertions(+), 443 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index b8192dfa..19f7fb95 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -31,340 +31,804 @@ Template:
 
 ## Diffusion models
 
-Diffusion MRI can be modeled using various paradigms to extract more
-informative representations of the diffusion process and the underlying
-biological structure. A wide range of such models are available, each of
-which has its own unique requirements with respect to:
-
--   The [input](#paramdef-input) parameters required in order to
-    define / constrain the way in which the model will be fit to the
-    empirical image data;
-
--   The appropriate [data representations](#data-representations) utilized to
-    store information parameterised [by](#paramdef-fit) or
-    [from](#paramdef-derived) the model onto the filesystem;
-
--   The requirements for encapsulation and complete representation of
-    derived [orientation information](#orientation-specification), which is
-    a key strength of diffusion MRI but presents unique challenges for
-    correct interpretation.
-
-### Parameter terminology
-
-Throughout this document, the term "parameter" is used to refer to
-multiple distinct sources of information. The distinction between
-these uses is defined thus:
-
-1.  <a name="paramdef-input">*Input*</a> parameter:
-
-    Value or non-numerical setting that influences the conformation
-    of the diffusion model to the empirical diffusion-weighted data.
-
-1.  <a name="paramdef-fit">Model *fit*</a> parameter:
-
-    Value that is the direct result of fitting the diffusion model to the
-    empirical diffusion-weighted data.
-
-1.  <a name="paramdef-derived">Model-*derived*</a> parameter:
-
-    Value that can be calculated directly from previously estimated
-    *model parameters*, without necessitating reference to
-    the empirical diffusion-weighted data.
-
-For example, consider a diffusion tensor model fit: the number of
-iterations in the optimization algorithm would be an *input* parameter;
-the six unique diffusion tensor coefficients would be the *model fit*
-parameters; the Fractional Anisotropy (FA) would be a *model-derived*
-parameter (as it is calculated from the diffusion tensor coefficients
-rather than the image data).
-
-### File names
+Diffusion MRI can be modeled using various paradigms
+to extract more informative representations of the diffusion process
+and the underlying biological structure.
+There are two key attributes of diffusion models
+that warrant explicit mention due to their consequence in how they are represented:
+
+-   The encoding of *anisotropic* information;
+    that is, quantities for which the value depends on the orientation in which it is sampled.
+    Much of the detail in diffusion derivatives is therefore dedicated
+    to the definition of how such data are serialised into corresponding NIfTI images,
+    and how corresponding metadata is used to facilitate correct interpretation of those data.
+
+-   A diffusion model may represent the contents of each image voxel as the sum of *multiple compartments*;
+    further, each of these different compartments may have different intrinsic properties,
+    such as units or anisotropy (as above).
+    An individual model fit may therefore yield data for its different parameters
+    distributed across multiple NIfTI images,
+    and each image may require unique metadata fields to facilitate interpretation.
+
+### Basic filesystem structure
 
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
         dwi/
-            <source_keywords>[_space-<space>]_model-<label>_param-<param1>_model.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>_param-<param1>_model.json
-            <source_keywords>[_space-<space>]_model-<label>_param-<param2>_model.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>_param-<param2>_model.json
-            <source_keywords>[_space-<space>]_model-<label>_model.json
-
-            [<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.nii[.gz]]
-            [<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.json]
-            [<source_keywords>[_space-<space>]_model-<label>_param-<paramb>_mdp.nii[.gz]]
-            [<source_keywords>[_space-<space>]_model-<label>_param-<paramb>_mdp.json]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.json
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.json
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.json
 ```
 
--   Files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_model.nii[.gz]`"
-    provide data corresponding to the various requisite [model fit parameters](#paramdef-fit).
-
-    In cases where *all* [model fit parameters](#paramdef-fit) are contained within a single image
-    file, entity "`_param-`" MUST NOT be included; e.g.:
-        ```Text
-        <pipeline_name>/
-            sub-<participant_label>/
-                dwi/
-                    <source_keywords>[_space-<space>]_model-<label>_model.nii[.gz]
-                    <source_keywords>[_space-<space>]_model-<label>_model.json
-        ```
-
--   File "`<source_keywords>[_space-<space>]_model-<label>_model.json`"
-    provides basic model information and [input parameters](#paramdef-input).
-
--   OPTIONAL images "`<source_keywords>[_space-<space>]_model-<label>_param-<parama>_mdp.nii[.gz]`"
-    may be defined, in order to provide additional [model-derived parameters](#paramdef-derived).
-
--   OPTIONAL files "`<source_keywords>[_space-<space>]_model-<label>_param-<param*>_mdp.json`"
-    may be defined to provide information or parameters only relevant to
-    each relevant [model-derived parameter](#paramdef-derived).
-
-### Data representations
-
-There are multiple techniques by which data that relate to the anisotropic
-nature of either the diffusion process or underlying tissue may be
-arranged and/or encoded into NIfTI image data. A list of known techniques
-is enumerated below, accompanied by requisite information specific to the
-reading / writing of each representation.
+-   Files "`<source_keywords>_model-<label>_param-<label*>_dwimap.nii[.gz]`"
+    provide image data encoding the different parameters that may be estimated by the model.
+    If the image is a three-dimensional volume,
+    then in the absence of any metadata indicating to the contrary,
+    the image should be interpreted as yielding a single scalar parameter per voxel.
+    If the image is of a higher dimensionality,
+    then relevant metadata fields MUST be specified in the corresponding sidecar JSON file
+    indicating how data across dimensions beyond the three spatial dimensions
+    should be interpreted.
+
+-   Files "`<source_keywords>_model-<label>_param-<label*>_dwimap.json`"
+    MUST provide information about the model,
+    and SHOULD provide information about how it was fit to the empirical image data.
+    In circumstances where the dimensionality of the corresponding NIfTI image is greater than three,
+    they MUST also specify requisite metadata fields regarding
+    how data across dimensions beyond the three spatial dimensions are to be interpreted.
+
+In cases where a pipeline yields only a single parameter from a model,
+entity "`_param-<label>`" MUST NOT be included; e.g.:
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>]_model-<label>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>_dwimap.json
+```
 
-For data that encode orientation information, there are fields that MUST
-be specified in the sidecar JSON file in order to ensure appropriate
-interpretation of that information; see [orientation specification](#orientation-specification)).
+### Orientation encoding types
 
-1.  <a name="data-scalar">*Scalars*</a>:
+There are many mathematical bases that may be used
+in the encoding of parameters that vary as a function of orientation.
+A list of such functions supported by the specification is enuerated below,
+accompanied by requisite information specific to each representation.
 
-    Any parameter image (whether [model fit](#paramdef-fit) or
-    [model-derived](#paramdef-derived)) where a solitary numerical value is
-    defined in each 3D image voxel is referred to here as a "scalar" image.
+For image data that encode orientation information,
+there are fields that MUST be specified in the sidecar JSON file
+in order to ensure appropriate interpretation of that information;
+see [parameter metadata](#parameter-metadata).
 
-1.  <a name="data-dec">*Directionally-Encoded colors (DEC)*</a>:
+1.  <a name="encoding-scalar">*Scalar image*</a>:
 
-    4D image with three volumes, intended to be interpreted as red, green
-    and blue color intensities for visualization
-    \[[Pajevic1999](#pajevic1999)\]. Image data MUST NOT contain negative
-    values.
+    Image data that do not encode orientation information
+    are referred to henceforth here as "scalar" parameters.
 
-1.  <a name="data-tensor">*Rank-2 tensor*</a>:
+1.  <a name="encoding-dec">*Directionally-Encoded Colors (DEC)*</a>:
 
-    4D image encoding coefficients of a rank-2 tensor.
-    If `"AntipodalSymmetry"` is `True` (or omitted),
-    then the image MUST contain six volumes, in the order:
-    *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>*, *D<sub>zz</sub>.
-    If `"AntipodalSymmetry"` is `False`,
-    then the image MUST contain nine volumes, in the order:
-    *D<sub>xx</sub>*, *D<sub>xy</sub>*, *D<sub>xz</sub>*, *D<sub>yx</sub>*, *D<sub>yy</sub>*, *D<sub>yz</sub>, *D<sub>zx</sub>*, *D<sub>zy</sub>*, *D<sub>zz</sub>.
-    (If `"ReferenceAxes"` is `"ijk"`, then the interpretation of the coefficients
-    above should be substituted accordingly)
+    An image with three volumes,
+    intended to be interpreted as red, green and blue color intensities for visualization.
+    Image data MUST NOT contain negative values.
 
-1.  <a name="data-spherical">*Spherical coordinates*</a>:
+1.  <a name="encoding-spherical">*Spherical coordinates*</a>:
 
-    4D image where data across volumes within each voxel encode one or
-    more discrete orientations using angles on the 2-sphere, optionally
-    exploiting the distance from origin to encode the value of some parameter.
+    An image where data across volumes within each voxel encode
+    one or more discrete orientations using angles on the 2-sphere,
+    optionally encoding some parameter as the distance from origin.
 
     This may take one of two forms:
 
     1.  Value per direction
 
-        Each consecutive triplet of image volumes encodes a spherical
-        coordinate, using ISO convention for both the order of parameters
+        Each consecutive triplet of image volumes encodes a 3-tuple spherical coordinate,
+        using ISO convention for both the order of parameters
         and reference frame for angles:
 
-        1.  Distance from origin; value of embedded parameter MUST be
-            indicated in "`_param-*`" entity;
+        1.  Distance from origin,
+            encoding some parameter of interest.
 
-        1.  Inclination / polar angle, in radians, relative to the zenith
-            direction being the positive direction of the *third* reference
-            axis (see [orientation specification](#orientation-specification));
+        1.  Inclination / polar angle in radians,
+            relative to the zenith direction being the positive direction of the *third* reference axis
+            (see [parameter metadata](#parameter-metadata));
 
-        1.  Azimuth angle, in radians, orthogonal to the zenith direction,
+        1.  Azimuth angle, in radians,
+            orthogonal to the zenith direction,
             with value of 0.0 corresponding to the *first* reference axis
-            (see [orientation specification](#orientation-specification)),
-            increasing according to the right-hand rule about the zenith
-            direction.
+            (see [parameter metadata](#parameter-metadata)),
+            increasing according to the right-hand rule about the zenith direction.
 
-        Number of image volumes is equal to (3x*N*), where *N* is the maximum
-        number of discrete orientations in any voxel in the image.
+        Number of image volumes is equal to (3x*N*),
+        where *N* is the maximum number of discrete orientations in any voxel in the image.
 
-    1.  Directions only
+    1.  Orientations only
 
-        Each consecutive pair of image volumes encodes inclination /
-        azimuth pairs, with order & convention identical to that above
-        (equivalent to spherical coordinate with assumed unity distance from
-        origin).
+        Each consecutive pair of image volumes encodes an inclination / azimuth pair,
+        with order & convention identical to that above
+        (equivalent to spherical coordinate with assumed unity distance from origin).
 
         Number of image volumes is equal to (2x*N*), where *N* is the maximum
         number of discrete orientations in any voxel in the image.
 
-1.  <a name="data-3vector">*3-Vectors*</a>:
+1.  <a name="encoding-3vector">*3-Vectors*</a>:
 
-    4D image where data across volumes within each voxel encode one or
-    more discrete orientations using triplets of axis dot products.
+    An image where data across volumes within each voxel encode
+    one or more discrete orientations
+    using triplets of axis dot products.
 
-    This representation may be used in one of two ways:
+    This may take one of two forms:
 
-    1.  Value per direction
+    1.  Value per orientation
 
-        Each 3-vector, once explicitly normalized, provides a direction
-        on the unit sphere; the *norm* of each 3-vector additionally encodes
-        the magnitude of some model or model-derived parameter, the nature of
-        which MUST be indicated in the "`_param-*`" entity.
+        The *norm* of the 3-vector encodes some parameter of interest,
+        while its normalized form encodes an orientation on the unit sphere.
+        Note that only non-negative parameters may be encoded in this form.
 
-    1.  Directions only
+    1.  Orientations only
 
         Each triplet of values encodes an orientation on the unit sphere
-        (i.e. the 3-vector data are normalized); no quantitative value is
-        associated with each triplet.
+        (i.e. the vector norm MUST be 1.0);
+        no quantitative value is associated with each orientation.
+
+    Number of image volumes is equal to (3x*N*),
+    where *N* is the maximum number of discrete orientations in any voxel in the image.
+
+1.  <a name="encoding-tensor">*Tensor*</a>:
 
-    Number of image volumes is equal to (3x*N*), where *N* is the maximum
-    number of discrete orientations in any voxel in the image.
+    An image where volumes encode coefficients of a tensor.
 
-1.  <a name="data-sh">*Spherical Harmonics (SH)*</a>:
+    -   For *Rank 2* tensors:
 
-    4D image where data across volumes within each voxel represent a
-    continuous function spanning the 2-sphere as coefficient values using a
-    spherical harmonics basis.
+        If antipodal symmetry is set (or implicitly assumed),
+        then the image MUST contain six volumes, in the order:
+        *D<sub>11</sub>*, *D<sub>12</sub>*, *D<sub>13</sub>*, *D<sub>22</sub>*, *D<sub>23</sub>*, *D<sub>33</sub>,
+        where *1*, *2* and *3* index the three spatial dimensions according to their reference
+        (see field `"OrientationEncoding"["Reference"]` in [parameter metadata](#parameter-metadata)).
+        If the data are not antipodally symmetric,
+        then the image MUST contain nine volumes, in the order:
+        *D<sub>11</sub>*, *D<sub>12</sub>*, *D<sub>13</sub>*, *D<sub>21</sub>*, *D<sub>22</sub>*, *D<sub>23</sub>, *D<sub>31</sub>*, *D<sub>32</sub>*, *D<sub>33</sub>,
+        with subscripts indexing row then column.
+
+1.  <a name="encoding-sh">*Spherical Harmonics (SH)*</a>:
+
+    Image where data across volumes within each voxel encode
+    a continuous function spanning the 2-sphere
+    using coefficients within a spherical harmonics basis.
 
     Number of image volumes depends on the spherical harmonic basis employed,
-    and the maximal spherical harmonic degree *l<sub>max</sub>* (see
-    [spherical harmonics bases](#spherical-harmonics-bases)).
+    and the maximal spherical harmonic degree *l<sub>max</sub>*
+    (see [spherical harmonics bases](#spherical-harmonics-bases)).
 
-1.  <a name="data-amp">*Amplitudes*</a>:
+1.  <a name="encoding-amp">*Amplitudes*</a>:
 
-    4D image where data across volumes within each voxel represent
+    Image where data across volumes within each voxel encode
     amplitudes of a discrete function spanning the 2-sphere.
 
-    Number of image volumes corresponds to the number of discrete directions
+    Number of image volumes corresponds to the number of discrete orientations
     on the unit sphere along which samples for the spherical function in
-    each voxel are provided; these directions MUST themselves be provided
-    in the associated sidecar JSON file (see [orientation specification](#orientation-specification)).
+    each voxel are provided;
+    these orientations MUST themselves be provided in the associated sidecar JSON file
+    (see [parameter metadata](#parameter-metadata)).
+
+### Bootstrap encoding
+
+For some models,
+it is common to export not only the best fit of the model to the empirical data,
+but multiple reaslisations of that fit taking into account image noise,
+typically through some form of bootstrapping procedure.
+Where this occurs,
+the image data for each parameter possess an additional dimension,
+along which those multiple realisations are stored.
+
+For some models,
+it is common to explicitly store *both* the multiple realisations of the model
+*and* either the parameters corresponding to the maximum *a posteriori* fit
+or the mean of each parameter computed across those realisations.
+In these circumstances,
+it is RECOMMENDED to use the same label for the "`_model-`" entity,
+and use the "`_desc-`" entity to disambiguate between these two versions
+at the filesystem level.
+
+### Metadata fields
+
+#### Model vs. parameter metadata
+
+For a NIfTI image that encodes some parameter of some model,
+there are are range of metadata fields that may be relevant.
+These can be broadly separated into two categories:
+
+1.  Metadata that apply to *the model as a whole*
+    are not specific to any individual parameter estimated by that model.
+    It is therefore RECOMMENDED that any such metadata
+    be *equivalent* across all sidecar JSON files for all parameters of that model.
+
+1.  Metadata that apply *only to that specific parameter*
+    may include attributes such as units and orientation encoding
+    essential for correct interpretation of that parameter image *only*.
+    it is therefore possible that these metadata fields may *differ*
+    across the multiple parameters estimated by that model.
+
+#### Model metadata
+
+At the root of the metadata dictionary,
+REQUIRED field `"Model"` defines a dictionary that contains relevant information
+about what the model is and how it was fit to empirical image data.
+The following table defines reserved fields within the `"Model"` sub-dictionary.
+
+| **Key name**        | **Description**                                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| BootstrapParameters | OPTIONAL. Dictionary. Parameters relating to the generation of multiple realisations of the model fit using bootstrapping.      |
+| Description         | OPTIONAL. String. Extended text-based information to describe the model.                                                        |
+| Parameters          | OPTIONAL. Dictionary. Parameters that influenced the process of fitting the model to empirical image data (see examples below). |
+| URL                 | OPTIONAL. String. URL to the specific implementation of the model utilized.                                                     |
+
+Dictionary `"Model["Parameters"]"` has the following reserved keywords that may be applicable to a broad range of models:
+
+| **Key name**           | **Description**                                                                                                                                                                                                                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FitMethod              | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Resrved values are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
+| Iterations             | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                           |
+| OutlierRejectionMethod | OPTIONAL. String. Text describing any form of rejection of outlier values that was performed during fitting of the model.                                                                                                                                                                                     |
+| Samples                | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters were computed.                                                                                                                                        |
+
+#### Parameter metadata
+
+The following table defines reserved fields relevant to individual model parameters.
+Some fields are applicable only to specific [orientation encoding types](#orientation-encoding-types).
+
+| **Key name**        | Relevant [orientation encoding types](#orientation-encoding-types)                              | **Description**                                                                                                                                                                                                                       |
+| ------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| BootstrapAxis       | Any                                                                                             | OPTIONAL. Integer. If multiple realisations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realisations are stored.                             |
+| Description         | Any                                                                                             | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
+| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [unit 3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularised to not take extreme negative values, or was explicitly forbidden from taking negative values. |
+| OrientationEncoding | Any                                                                                             | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
+| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                             | OPTIONAL. Dictionary. Specifies a response function that was utilised by a deconvolution algorithm; more details below.                                                                                                               |
+
+Dictionary `"OrientationEncoding"` has the following reserved keywords:
+
+| **Key name**            | Relevant [orientation encoding types](#orientation-encoding-types)                                                                                                         | **Description**                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| AmplitudesDirections    | [Amplitudes](#encoding-amp)                                                                                                                                                | REQUIRED for `"Type": "amplitudes"`; MUST NOT be specified otherwise. List of lists of floats. Data are either [spherical coordinates (directions only)](#encoding-spherical) or [3-vectors](#encoding-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. The length of the list must be equal to the number of volumes in the image. |
+| AntipodalSymmetry       | [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector), [tensor](#encoding-tensor), [amplitudes](#encoding-amp), [spherical harmonics](#encoding-sh) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                                                                                                                                                                                            |
+| EncodingAxis            | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding.                                                                                                                                                                                                                                                                |
+| FillValue               | [Scalar](#encoding-scalar), [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector)                                                                   | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when the number of discrete orientations in a given voxel is fewer than the maximal number for that image.                                                                                                                                                                                                                                              |
+| Reference               | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                                                                                                                                                                                   |
+| SphericalHarmonicBasis  | [Spherical harmonics](#encoding-sh)                                                                                                                                        | REQUIRED for `"Type": "sh"`; MUST NOT be specified otherwise. String. Options are: { `mrtrix3`, `descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                                                                                                                                 |
+| SphericalHarmonicDegree | [Spherical harmonics](#encoding-sh)                                                                                                                                        | OPTIONAL for `"Type": "sh"`; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                       |
+| TensorRank              | [Tensor](#encoding-tensor)                                                                                                                                                 | REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2.                                                                                                                                                                                                                                                                |
+| Type                    | Any                                                                                                                                                                        | REQUIRED. String. Specifies the type of orientation information (if any) encoded in the NIfTI image. Permitted values: { `scalar`, `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `tensor`, `sh`, `amplitudes` }.                                                                                                                                                                                            |
+
+Dictionary `"ResponseFunction"` has the following reserved keywords:
+
+| **Key name** | **Description**                                                                                                                                                                            |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Coefficients | REQUIRED. Either a list of floats, or a list of lists of floats, depending on the mathematical form of the response function and possibly the data to which it applies; see further below. |
+| Type         | REQUIRED. String. Options are: { `eigen`, `zsh` }. The mathematical form in which the response function coefficients are provided; see further below.                                      |
+
+-   If `"ResponseFunction"["Type"]: "eigen"`,
+    then a list of 4 floating-point values must be specified;
+    these are interpreted as three ordered eigenvalues of a rank 2 tensor,
+    followed by a reference *b*=0 intensity.
+
+-   If `"ResponseFunction"["Type"]": "zsh`",
+    then the values provided can be one of the following:
+
+    -   List of floating-point values.
+        Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero.
+
+    -   List of lists of floating-point values.
+        One list per unique *b*-value.
+        Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero.
+        If the response function utilised has a different number of non-zero zonal spherical harmonic coefficients for different *b*-values,
+        these must be padded with zeroes such that all lists contain the same number of floating-point values.
+
+### Demonstrative examples
 
-1.  <a name="data-param">*Parameter vectors*</a>:
+-   A basic Diffusion Tensor fit:
 
-    4D image containing, for every image voxel, data corresponding to some
-    set of model parameters, the names and order of which are defined within
-    the [model fit parameters](#paramdef-fit) section below.
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_model-tensor_param-diffusivity_dwimap.nii.gz
+                sub-01_model-tensor_param-diffusivity_dwimap.json
+                sub-01_model-tensor_param-s0_dwimap.nii.gz
+                sub-01_model-tensor_param-s0_dwimap.json
+                sub-01_model-tensor_param-fa_dwimap.nii.gz
+                sub-01_model-tensor_param-fa_dwimap.json
+    ```
 
-### Model parameters
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K*x6 ([symmetric rank 2 tensor image](#encoding-tensor))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+    Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
 
-The following models are codified within the specification. The model label
-should be included in the "`_model-`" entity in the filename for storage
-of both model and model-derived parameters. Some models necessitate reserved
-keywords for "`_param-`" fields, which are listed below.
+    Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
+    ```JSON
+    {
+        "Description": "Diffusion Coefficient, encoded as a tensor representation",
+        "Model": {
+            "Description": "Diffusion Tensor",
+            "Parameters": {
+                "FitMethod": "ols",
+                "OutlierRejectionMethod": "None"
+            }
+        },
+        "OrientationEncoding": {
+            "AntipodalSymmetry": true,
+            "EncodingAxis": 3,
+            "Reference": "xyz",
+            "TensorRank": 2,
+            "Type": "tensor"
+        },
+        "Units": "mm^2/s"
+    }
+    ```
 
-| Model label | Full Name                                                                                                                                       | [Data representation](#data-representations)                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bs`        | Ball-and-Stick(s) model \[[Behrens2003](#behrens2003)\],\[[Behrens2007](#behrens2007)\],\[[Jbabdi2012](#jbabdi2012)\]                           | One [spherical coordinates](#data-spherical) image with parameter name "`sticks`", providing both fibre volume fractions and orientations using polar angles;<br>Optional scalar images with parameter names {"`bzero`", "`dmean`", "`dstd`"} providing the model-estimated *b*=0 signal intensity, mean stick diffusivity, and standard deviation of stick diffusivities respectively                              |
-| `csd`       | Constrained Spherical Deconvolution \[[Tournier2007](#tournier2007)\],\[[Descoteaux2009](#descoteaux2009)\],\[[Jeurissen2014](#jeurissen2014)\] | [Spherical harmonics](#data-sh) image<br>If a multi-tissue decomposition is performed, provide one individual 4D image per tissue, with "`_param-<param>`" entity being an abbreviation of the tissue estimated by that particular ODF                                                                                                                                                                        |
-| `tensor`    | Diffusion Tensor \[[Basser1994](#basser1994)\]                                                                                                  | Single [tensor image](#data-tensor) with no `param` entity <br>OR<br>Tensor coefficients as [tensor image](#data-tensor) image with `param` entity ``tensor``;<br>Estimated *b*=0 intensity as [scalar image](#data-scalar) with `param` entity "`bzero`" |
+    Contents of file `sub-01_model-tensor_param-s0_dwimap.json`:
+    ```JSON
+    {
+        "Description": "Estimated signal intensity with no diffusion weighting, ie. S0",
+        "Model": {
+            "Description": "Diffusion Tensor",
+            "Parameters": {
+                "FitMethod": "ols",
+                "OutlierRejectionmethod": "None"
+            }
+        }
+    }
+    ```
 
-The JSON sidecar for the intrinsic diffusion model parameters may contain
-the following key/value pairs irrespective of the particular model:
+    Contents of file `sub-01_model-tensor_param-fa_dwimap.json`:
+    ```JSON
+    {
+        "Description": "Fractional Anisotropy",
+        "Model": {
+            "Description": "Diffusion Tensor",
+            "Parameters": {
+                "FitMethod": "ols",
+                "OutlierRejectionmethod": "None"
+            }
+        }
+    }
+    ```
 
-| **Key name**     | **Description**                                                                                                                                                                              |
-| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Gradients        | OPTIONAL. List of 3-vectors. Subset of gradients utilized to fit the model, as a list of three-elements lists. If not present, all gradients were used.                                      |
-| Shells           | OPTIONAL. List of floats. Shells that were utilized to fit the model, as a list of b-values. If the key is not present, it should be assumed that all shells were used during model fitting. |
-| Mask             | OPTIONAL. String. Name of image that was used as a binary mask to specify those voxels for which the model was fit.                                                                          |
-| ModelDescription | OPTIONAL. String. Extended information to describe the model.                                                                                                                                |
-| ModelURL         | OPTIONAL. String. URL to the implementation of the specific model utilized.                                                                                                                  |
-| Parameters       | OPTIONAL. Dictionary. [Input](#paramdef-input) model parameters that are constant across the image (see examples below).                                                                     |
+    Notes:
 
-#### Model bootstrapping
+    -   "The diffusion tensor" intrinsically is a mathematical model of how
+        the diffusivity is estimated to vary as a function of orientation.
+        As such, within this model,
+        it is not the *parameter* that is a tensor;
+        rather, it is the *diffusivity* that is the estimated parameter,
+        and the *way in which the anisotropy of that parameter is encoded* is a tensor.
 
-Results of model bootstrapping can be provided by concatenating multiple
-realisations of model intrinsic parameters along an additional image axis.
+    -   Metadata fields relevant to the interpretation of the anisotropy of the tensor
+        are *not relevant* to the scalar measures
+        "`s0`" (estimated signal intensity with no diffusion weighting)
+        or "`fa`" (Fractional Anisotropy).
+        Those fields therefore MUST be omitted from the corresponding sidecar JSONs.
 
-The corresponding sidecar JSON file may include dictionary field
-"`BootstrapParameters`", describing those input parameters specific to
-the determination and export of multiple realisations of the model fit
-in each image voxel.
+-   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
 
-### Input model parameters
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_model-csd_param-wm_dwimap.nii.gz
+                sub-01_model-csd_param-wm_dwimap.json
+                sub-01_model-csd_param-gm_dwimap.nii.gz
+                sub-01_model-csd_param-gm_dwimap.json
+                sub-01_model-csd_param-csf_dwimap.nii.gz
+                sub-01_model-csd_param-csf_dwimap.json
+    ```
 
-Parameters that may / must be stored within the JSON sidecar "`Parameters`"
-field depends on the particular model used.
+    Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
+    Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
+    Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
 
-"`Parameters`" fields that may be applicable to multiple models:
+    Contents of JSON file "`sub-01_model-csd_param-wm_model.json`":
 
-| **Key name**     | **Description**                                                                                                                                                                                                                                                                                        |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FitMethod        | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Options are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
-| Iterations       | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                    |
-| OutlierRejection | OPTIONAL. Boolean. Value indicating whether or not rejection of outlier values was performed during fitting of the intrinsic model parameters.                                                                                                                                                         |
-| Samples          | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters are provided.                                                                                                                                  |
+    ```JSON
+    {
+        "Model": {
+            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+        },
+        "Description": "White matter",
+        "NonNegativity": "constrained",
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "Reference": "xyz",
+            "SphericalHarmonicBasis": "MRtrix3",
+            "SphericalHarmonicDegree": 8,
+            "Type": "sh",
+        },
+        "ResponseFunction": {
+            "Coefficients": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
+                              [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
+                              [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
+                              [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
+            "Type": "zsh"
+        }
+    }
+    ```
 
-Reserved keywords for models built into the specification are as follows:
+    Contents of JSON file "`sub-01_model-csd_param-gm_dwimap.json`":
 
--   `bs` :
+    ```JSON
+    {
+        "Model": {
+            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+        },
+        "Description": "Gray matter",
+        "NonNegativity": "constrained",
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "Reference": "xyz",
+            "SphericalHarmonicBasis": "MRtrix3",
+            "SphericalHarmonicDegree": 0,
+            "Type": "sh",
+        },
+        "ResponseFunction": {
+            "Coefficients": [ [ 1041.0 ],
+                              [ 436.6 ],
+                              [ 224.9 ],
+                              [ 128.8 ] ],
+            "Type": "zsh"
+        }
+    }
+    ```
 
-    -   `ARDFudgeFactor`: Float. Weight applied to Automatic Relevance Determination (ARD).
-    -   `Fibers`: Integer. Number of discrete fibres to fit in each voxel.
-    -   `ModelBall`: String. Model used to describe the "ball" component in the model.
-    -   `ModelSticks`: String. Model used to describe the "stick" component in the model.
+    Contents of JSON file "`sub-01_model-csd_param-csf_dwimap.json`":
 
--   `csd`:
+    ```JSON
+    {
+        "Model": {
+            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+        },
+        "Description": "Cerebro-spinal fluid",
+        "NonNegativity": "constrained",
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "Reference": "xyz",
+            "SphericalHarmonicBasis": "MRtrix3",
+            "SphericalHarmonicDegree": 0,
+            "Type": "sh"
+        },
+        "ResponseFunction": {
+            "Coefficients": [ [ 544.90770181 ],
+                              [ 134.441453035 ],
+                              [ 32.0826839826 ],
+                              [ 29.3674604452 ] ],
+            "Type": "zsh"
+        }
+    }
+    ```
 
-    -   `NonNegativityConstraint`: String. Options are: { `soft`, `hard` }. Specifies whether the ODF was estimated using regularization ("`soft`") or prevention ("`hard`") of negative values.
+    Notes:
 
-    -   `ResponseFunctionZSH`: Two options:
+    -   In this example,
+        the gray matter and CSF compartments are specified in the spherical harmonics basis
+        with maximal spherical harmonic degrees of zero,
+        even though each image only contains a single volume
+        and could therefore be interpreted as simply scalar parameters.
+        This is recommended in this instance
+        given that the spherical harmonic basis imposes a $\sqrt(4\pi)$ scaling
+        that should be taken into account if comparing the values of these parameters
+        with the *l*=0 term of the white matter ODF.
 
-        -   Vector of floating-point values, where values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero (in this case field "`Shells`" should contain a single integer value);
-        -   Matrix of floating-point values: 1 row per unique *b*-value as listed in "`Shells`"; 1 column per even zonal spherical harmonic degree starting from zero; if there are a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all rows contain the same number of columns.
+    -   The response functions for GM and CSF have a maximal zonal spherical harmonic degree of zero,
+        such that only one coefficient is required for each unique *b*-value shell.
+        It is however nevertheless vital that these data be provided as a list of lists of floats,
+        where the length of each list is one;
+        storing these values as a list of floats would be erroneously interpreted
+        as coefficients of different zonal spherical harmonic degrees for a single *b*-value shell.
 
-    -   `ResponseFunctionTensor`: Vector of 4 floating-point values: three tensor eigenvalues, then reference *b*=0 intensity
+-   An FSL `bedpostx` Ball-And-Sticks fit
+    (including both mean parameters and bootstrap realisations):
 
-    -   `SphericalHarmonicBasis`: String. Options are: { `MRtrix3` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+    ```Text
+    my_diffusion_pipeline/
+        sub-01/
+            dwi/
+                sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-s0_dwimap.json
+                sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-polar_dwimap.json
+                sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-vector_dwimap.json
+                sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-vf_dwimap.json
+                sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-vfsum_dwimap.json
+                sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json
+                sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz
+                sub-01_model-bs_desc-mean_param-dstd_dwimap.json
+                sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz
+                sub-01_model-bs_desc-merged_param-polar_dwimap.json
+                sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz
+                sub-01_model-bs_desc-merged_param-vf_dwimap.json
+    ```
 
-    -   `SphericalHarmonicDegree`: Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*) ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel)
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz`": *I*x*J*x*K*x(*3*x*N*) ([3-vectors](#encoding-3vectors), unit norm; *N* orientations per voxel)
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N* ([scalar](#encoding-scalar); *N* values per voxel)
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*)x*R* ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel; *R* bootstrap realisations)
+    Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N*x*R* ([scalar](#encoding-scalar); *N* values per voxel; *R* bootstrap realisations)
 
-    -   `Tissue`: String. A more verbose description for the tissue estimated via this specific ODF.
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-s0_dwimap.json`":
 
--   `tensor` :
+    ```JSON
+    {
+        "Description": "Estimated signal intensity with no diffusion weighting, ie. S0; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        }
+    }
+    ```
 
-    -   `RESTORESigma`: Float
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-polar_dwimap.json`":
 
-### Model-derived parameters
+    ```JSON
+    {
+        "Description": "Fibre orientations encoded using polar angles; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "Reference": "ijk",
+            "Type": "unitspherical"
+        }
+    }
+    ```
 
-| `<parameter>` value | Description                                                            | [Data representation](#data-representations) | Possible Model sources | Unit or scale                                                  |
-| ------------------- | ---------------------------------------------------------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------------------------- |
-| `ad`                | Axial Diffusivity (also called parallel diffusivity)                   | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `afdtotal`          | Total Apparent Fibre Density (AFD) \[[Calamante2015](#calamante2015)\] | [Scalar](#data-scalar)                       | { `csd` }              | Unitless                                                       |
-| `cl`                | Tensor linearity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
-| `cp`                | Tensor planarity \[[Westin1997](#westin1997)\]                         | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
-| `cs`                | Tensor sphericity \[[Westin1997](#westin1997)\]                        | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
-| `evec`              | Eigenvector(s)                                                         | [3-vectors](#data-3vector)                   | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `fa`                | Fractional Anisotropy \[[Basser1996](#basser1996)\]                    | [Scalar](#data-scalar)                       | { `tensor` }           | Proportion \[0.0-1.0\]                                         |
-| `fsum`              | Sum of partial volume fractions of stick components                    | [Scalar](#data-scalar)                       | { `bs` }               | Volume fraction \[0.0-1.0\]                                    |
-| `gfa`               | Generalized Fractional Anisotropy \[[Tuch2004](#tuch2004)\]            | [Scalar](#data-scalar)                       | { `csd` }              | Proportion \[0.0-1.0\]                                         |
-| `md`                | Mean diffusivity (also called apparent diffusion coefficient, ADC)     | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
-| `mode`              | Mode of the tensor                                                     | [Scalar](#data-scalar)                       | { `tensor` }           |                                                                |
-| `peak`              | Direction(s) and amplitude(s) of ODF maximum (maxima)                  | [3-vectors](#data-3vector)                   | { `csd` }              | Same units as ODF                                              |
-| `rd`                | Radial Diffusivity (also called perpendicular diffusivity)             | [Scalar](#data-scalar)                       | { `tensor` }           | \mu m<sup>2</sup>.ms<sup>-1</sup> <sup>[1](#diffusivity)</sup> |
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vector_dwimap.json`":
 
-While not explicitly included in the table above, *any* [scalar](#data-scalar)
-[model-derived parameter](paramdef-derived) can theoretically be combined
-with a separate source of orientation information from the diffusion model
-in order to produce a [directionally-encoded color](#data-dec),
-[spherical coordinates](#data-spherical) or [3-vectors](#data-3vector) image.
+    ```JSON
+    {
+        "Description": "Fibre orientations encoded using 3-vectors; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "Reference": "ijk",
+            "Type": "unit3vector"
+        }
+    }
 
-### Orientation specification
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vf_dwimap.json`":
 
-| **Key name**                | **Relevant [data representations](#data-representations)**                                                                                                       | **Description**                                                                                                                                                                                                                                           |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AntipodalSymmetry`         | [Tensor](#data_tensor), [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector), [spherical harmonics](#data-sh), [amplitudes](#data-amp), [parameter vectors](#data-param) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                         |
-| `Directions`                | [Amplitudes](#data-amp)                                                                                                                                          | REQUIRED. List. Data are either [spherical coordinates (directions only)](#data-spherical) or [3-vectors](#data-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. |
-| `FillValue`                 | [Spherical coordinates](#data-spherical), [3-vectors](#data-3vector)                                                                                             | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when number of discrete orientations in a voxel is fewer than the maximal number for that image.                                                                                     |
-| `OrientationRepresentation` | All except [scalar](#data-scalar)                                                                                                                                | REQUIRED. String; allowed values: { `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `sh`, `amp`, `param` }. The [data representation](#data-representations) used to encode orientation information within the NIfTI image.                |
-| `ReferenceAxes`             | All except [scalar](#data-scalar)                                                                                                                                | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                |
-| `SphericalHarmonicBasis`    | [Spherical harmonics](#data-sh)                                                                                                                                  | REQUIRED. String; allowed values: { `MRtrix3` }. Basis by which to define the interpretation of image values across volumes as spherical harmonics coefficients.                                                                                          |
-| `SphericalHarmonicDegree`   | [Spherical harmonics](#data-sh)                                                                                                                                  | REQUIRED. Integer. Maximal degree of the spherical harmonic basis employed.                                                                                                                                                                               |
+    ```JSON
+    {
+        "Description": "Volume fractions of stick components; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "OrientationEncoding": {
+            "Type": "scalar"
+        }
+    }
 
-If `AntipodalSymmetry` is True, then no constraints are imposed with respect
-to the domain on the 2-sphere in which orientations may be specified;
-for instance, 3-vectors { 0.57735, 0.57735, 0.57735 } and
-{ -0.57735, -0.57735, -0.57735 } are both permissible and equivalent to one
-another.
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.json`":
+
+    ```JSON
+    {
+        "Description": "Sum of volume fractions of stick components; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        }
+    }
+
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json`":
+
+    ```JSON
+    {
+        "Description": "Diffusivity; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "Units": "mm^2/s"
+    }
+
+    Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
+
+    ```JSON
+    {
+        "Description": "Diffusivity variance parameter; mean across bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "Units": "TODO"
+    }
+
+    Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
+
+    ```JSON
+    {
+        "BootstrapAxis": 4,
+        "Description": "Fibre orientations encoded using polar angles; concatenated bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "OrientationEncoding": {
+            "EncodingAxis": 3,
+            "ReferenceAxes": "ijk",
+            "Type": "unitspherical"
+        }
+    }
+
+    Contents of JSON file "`sub-01_model-bs_desc-merged_param-vf_dwimap.json`":
+
+    ```JSON
+    {
+        "BootstrapAxis": 4,
+        "Description": "Volume fractions of stick components; concatenated bootstrap realisations",
+        "Model": {
+            "Description": "Ball-And-Sticks model using FSL bedpostx",
+            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+            "Parameters": {
+                "ARDFudgeFactor": 1.0,
+                "Fibers": 3
+            },
+            "BootstrapParameters": {
+                "Burnin": 1000,
+                "Jumps": 1250,
+                "SampleEvery": 25
+            }
+        },
+        "OrientationEncoding": {
+            "Type": "scalar"
+        }
+    }
+
+    Notes:
+
+    -   Here the descriptors "`merged`" and "`mean`" have been utilised
+        to distinguish between the comprehensive set of all bootstrap realisations
+        and the computed mean statistics of parameters across all realisations respectively,
+        as this is the terminology utilised by the FSL software itself.
+        These labels are not however a part of the specification.
+
+    -   Care must be taken for images of greater than three dimensions
+        where additional dimensions do *not* encode anisotropy information:
+
+        -   In image `"*_desc-mean*_param-vf_*"`,
+            the fourth image axis encodes scalar information across stick components.
+            Since this is *not* coefficients in some orientation encoding,
+            but the image possesses more than three axes,
+            field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+        -   Image `"*_param-vfsum_*"`is a three-dimensional image,
+            and therefore the fact that it encodes a scalar parameter
+            can be robustly inferred without reference to metadata information.
+
+        -   In image `"sub-01_model-bs_desc-merged_param-vf_dwimap.json"`,
+            there are two extra image dimensions beyond the three spatial dimensions:
+            the fourth image axis encodes across the multiple stick components per voxel,
+            and the fifth axis encodes realisations across bootstraps.
+            it is therefore necessary to explicitly specify
+            that the parameter being encoded in the data,
+            being the volume fractions of individual stick components,
+            do not have any anisotropy,
+            and therefore field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+    -   TODO CONFIRM WHETHER WE WANT TO ENFORCE THIS OR INCLUDE EXPLICIT METADATA FIELDS
+        THAT INDICATE THE AXIS / AXES OF DIRECTION ENCODING VS. BOOTSTRAP REALISATIONS
+
+    -   TODO DISCUSS
+        The example presented here is not necessarily a unique solution
+        for the storage of the outcomes of the FSL `bedpostx` command as BIDS Derivatives:
+
+        -   WOULD SPLITTING STICK COMPONENTS ACROSS NIFTIS
+            REQUIRE A NEW ENTITY BY WHICH TO INDEX THEM?
+            OR JUST GIVE THEM EG. `_param-spherical1`, `_param-spherical2`?
+
+        -   While the FSL `bedpostx` command yields the fibre orientation for each individual stick
+            as polar angles within separate NIfTI images,
+            for BIDS it is RECOMMENDED that such orientation information be encoded
+            either as [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector).
+
+        -   Given that it is possible to encode a scalar parameter
+            into either [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector) encodings,
+            it is possible to store an image that encodes,
+            for each stick component,
+            both volume fraction and orientation.
+            It is however RECOMMENDED to encode this information in separate files,
+            given that in the more general case there may be multiple scalar parameters
+            individually attributed to each component.
+
+### Appendix
 
 #### Spherical Harmonics
 
@@ -391,11 +855,11 @@ another.
 
     -   Utilized basis functions:
 
-        -   `MRtrix3`
+        -   `mrtrix3`
 
         ![MRtrix3 SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
 
-        -   `Descoteaux`
+        -   `descoteaux`
 
         ![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
 
@@ -421,9 +885,9 @@ another.
 
         *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-        | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | ...  |
-        | --------------------- |--:|--:|--: |--: |--: | :--: |
-        | ***N***               | 1 | 6 | 15 | 28 | 45 | ...  |
+        | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | 10 | ...  |
+        | --------------------- |--:|--:|--: |--: |--: |--: | :--: |
+        | ***N***               | 1 | 6 | 15 | 28 | 45 | 66 | ...  |
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
@@ -432,190 +896,6 @@ another.
 
         *N* = 1 + (*l<sub>max</sub>* / 2)
 
-        | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | ...  |
-        | --------------------- |--:|--:|--:|--:|--:| :--: |
-        | ***N***               | 1 | 2 | 3 | 4 | 5 | ...  |
-
-
-## Demonstrative examples
-
--   A basic Diffusion Tensor fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-tensor_param-tensor_model.nii.gz
-                sub-01_model-tensor_param-bzero_model.nii.gz
-                sub-01_model-tensor_param-fa_mdp.nii.gz
-                sub-01_model-tensor_model.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-tensor_model.nii.gz`": *I*x*J*x*K*x6 ([tensor image](#data-tensor))
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-
-    Contents of JSON file:
-
-    ```JSON
-    {
-        "ModelDescription": "Diffusion Tensor",
-        "OrientationRepresentation": "param",
-        "ReferenceAxes": "xyz",
-        "Parameters": {
-            "FitMethod": "ols",
-            "OutlierRejection": false
-        }
-    }
-    ```
-
--   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-csd_param-wm_model.nii.gz
-                sub-01_model-csd_param-wm_model.json
-                sub-01_model-csd_param-gm_model.nii.gz
-                sub-01_model-csd_param-gm_model.json
-                sub-01_model-csd_param-csf_model.nii.gz
-                sub-01_model-csd_param-csf_model.json
-                sub-01_model-csd_model.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-    Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#data-sh))
-
-    Contents of file "`sub-01_model-csd_model.json`" (common to all [model fit parameters](#paramdef-fit)):
-
-    ```JSON
-    {
-        "ModelDescription": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-        "ModelURL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
-        "Shells": [ 0, 1000, 2000, 3000 ],
-        "Parameters": {
-            "SphericalHarmonicBasis": "MRtrix3",
-            "NonNegativityConstraint": "hard"
-        }
-    }
-    ```
-
-    Contents of JSON file "`sub-01_model-csd_param-wm_model.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "sh",
-        "ReferenceAxes": "xyz",
-        "ResponseFunctionZSH": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
-                                 [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
-                                 [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
-                                 [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
-        "SphericalHarmonicDegree": 8,
-        "Tissue": "White matter"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_model-csd_param_gm_model.json`":
-
-    ```JSON
-    {
-        "OrientationRepresentation": "sh",
-        "ReferenceAxes": "xyz",
-        "ResponseFunctionZSH": [ [ 1041.0 ],
-                                 [ 436.6 ],
-                                 [ 224.9 ],
-                                 [ 128.8 ] ],
-        "SphericalHarmonicDegree": 0,
-        "Tissue": "Gray matter"
-    }
-    ```
-
--   An FSL `bedpostx` Ball-And-Sticks fit (including both mean parameters and
-    bootstrap realisations):
-
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-bs_param-bzero_model.nii.gz
-                sub-01_model-bs_param-bzero_model.json
-                sub-01_model-bs_param-md_mdp.nii.gz
-                sub-01_model-bs_param-md_mdp.json
-                sub-01_model-bs_param-stdd_mdp.nii.gz
-                sub-01_model-bs_param-stdd_mdp.json
-                sub-01_model-bs_param-sticks_mdp.nii.gz
-                sub-01_model-bs_param-sticks_mdp.json
-                sub-01_model-bs_param-sticks_model.nii.gz
-                sub-01_model-bs_param-sticks_model.json
-                sub-01_model-bs_model.json
-    ```
-
-    Dimensions of NIfTI image "`sub-01_model-bs_param-bzero_model.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_param-ms_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_param-stdd_mdp.nii.gz`": *I*x*J*x*K* ([scalar](#data-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_param-sticks_mdp.nii.gz`": *I*x*J*x*K*x9 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction)
-    Dimensions of NIfTI image "`sub-01_model-bs_param-sticks_model.nii.gz`": *I*x*J*x*K*x9x50 ([spherical coordinates](#data-spherical), distance from origin encodes fibre volume fraction; 50 bootstrap realisations)
-
-    Contents of JSON files "`sub-01_model-bs_param-sticks_mdp.json`"
-    and "`sub-01_model-bs_param-sticks_model.json`" (contents of two
-    files are identical):
-
-    ```JSON
-    {
-        "OrientationRepresentation": "spherical",
-        "ReferenceAxes": "ijk"
-    }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_model.json`":
-
-    ```JSON
-    {
-        "ModelDescription": "Ball-And-Sticks model using FSL bedpostx",
-        "ModelURL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-        "Parameters": {
-            "ARDFudgeFactor": 1.0,
-            "Fibers": 3,
-            "Samples": 50
-        },
-        "BootstrapParameters": {
-            "Burnin": 1000,
-            "Jumps": 1250,
-            "SampleEvery": 25
-        }
-    }
-    ```
-
----
-
-<a name="diffusivity"><sup>1</sup></a>: For example, for free water in body
-temperature, the diffusivity in units of \mu m<sup>2</sup>.ms<sup>-1</sup>
-should be approximately 3.0.
-
----
-
-<a name="basser1994">\[Basser1994\]</a>: Basser et al. 1994
-
-<a name="basser1996">\[Basser1996\]</a>: Basser et al. 1996
-
-<a name="behrens2003">\[Behrens2003\]</a> Behrens et al. 2003
-
-<a name="behrens2007">\[Behrens2007\]</a> Behrens et al. 2007
-
-<a name="calamante2015">\[Calamante2015\]</a>: Calamante et al. 2015
-
-<a name="descoteaux2009">\[Descoteaux2009\]</a>: Descoteaux et al. 2009
-
-<a name="jbabdi2012">\[Jbabdi2012\]</a> Jbabdi et al. 2012
-
-<a name="jeurissen2014">\[Jeurissen2014\]</a>: Jeurissen et al. 2014
-
-<a name="pajevic1999">\[Pajevic1999\]</a>: Pajevic et al 1999
-
-<a name="tournier2007">\[Tournier2007\]</a>: Tournier et al. 2007
-
-<a name="tuch2004">\[Tuch2004\]</a>: Tuch 2004
-
-<a name="westin1997">\[Westin1997\]</a>: Westin 1997
+        | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | 10 | ...  |
+        | --------------------- |--:|--:|--:|--:|--:|--: | :--: |
+        | ***N***               | 1 | 2 | 3 | 4 | 5 | 6  | ...  |

From a2c35b8fd6729945abb7184a7f16ecfa915db265 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 26 Apr 2024 14:42:53 +1000
Subject: [PATCH 50/65] BEP016: Fis JSON formatting in demonstrative examples

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 19f7fb95..21761384 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -346,6 +346,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
     Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
 
     Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
+
     ```JSON
     {
         "Description": "Diffusion Coefficient, encoded as a tensor representation",
@@ -368,6 +369,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
     ```
 
     Contents of file `sub-01_model-tensor_param-s0_dwimap.json`:
+
     ```JSON
     {
         "Description": "Estimated signal intensity with no diffusion weighting, ie. S0",
@@ -382,6 +384,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
     ```
 
     Contents of file `sub-01_model-tensor_param-fa_dwimap.json`:
+
     ```JSON
     {
         "Description": "Fractional Anisotropy",
@@ -500,7 +503,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
             "Type": "sh"
         },
         "ResponseFunction": {
-            "Coefficients": [ [ 544.90770181 ],
+            "Coefficients": [ [ 3544.90770181 ],
                               [ 134.441453035 ],
                               [ 32.0826839826 ],
                               [ 29.3674604452 ] ],
@@ -636,6 +639,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
             "Type": "unit3vector"
         }
     }
+    ```
 
     Contents of JSON file "`sub-01_model-bs_desc-mean_param-vf_dwimap.json`":
 
@@ -659,6 +663,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
             "Type": "scalar"
         }
     }
+    ```
 
     Contents of JSON file "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.json`":
 
@@ -679,6 +684,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
             }
         }
     }
+    ```
 
     Contents of JSON file "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json`":
 
@@ -700,6 +706,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
         },
         "Units": "mm^2/s"
     }
+    ```
 
     Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
 

From 8672cbe2462bb89790e459f432ea8cc7dd34e67c Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 26 Apr 2024 14:50:51 +1000
Subject: [PATCH 51/65] Diffusion models: Forbid negative spherical coordinate
 radius

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 21761384..0df97d43 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -129,7 +129,7 @@ see [parameter metadata](#parameter-metadata).
         and reference frame for angles:
 
         1.  Distance from origin,
-            encoding some parameter of interest.
+            encoding some non-negative parameter of interest.
 
         1.  Inclination / polar angle in radians,
             relative to the zenith direction being the positive direction of the *third* reference axis
@@ -163,9 +163,8 @@ see [parameter metadata](#parameter-metadata).
 
     1.  Value per orientation
 
-        The *norm* of the 3-vector encodes some parameter of interest,
+        The *norm* of the 3-vector encodes some non-negative parameter of interest,
         while its normalized form encodes an orientation on the unit sphere.
-        Note that only non-negative parameters may be encoded in this form.
 
     1.  Orientations only
 
@@ -279,13 +278,13 @@ Dictionary `"Model["Parameters"]"` has the following reserved keywords that may
 The following table defines reserved fields relevant to individual model parameters.
 Some fields are applicable only to specific [orientation encoding types](#orientation-encoding-types).
 
-| **Key name**        | Relevant [orientation encoding types](#orientation-encoding-types)                              | **Description**                                                                                                                                                                                                                       |
-| ------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| BootstrapAxis       | Any                                                                                             | OPTIONAL. Integer. If multiple realisations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realisations are stored.                             |
-| Description         | Any                                                                                             | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
-| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [unit 3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularised to not take extreme negative values, or was explicitly forbidden from taking negative values. |
-| OrientationEncoding | Any                                                                                             | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
-| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                             | OPTIONAL. Dictionary. Specifies a response function that was utilised by a deconvolution algorithm; more details below.                                                                                                               |
+| **Key name**        | Relevant [orientation encoding types](#orientation-encoding-types)                         | **Description**                                                                                                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| BootstrapAxis       | Any                                                                                        | OPTIONAL. Integer. If multiple realisations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realisations are stored.                             |
+| Description         | Any                                                                                        | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
+| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularised to not take extreme negative values, or was explicitly forbidden from taking negative values. |
+| OrientationEncoding | Any                                                                                        | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
+| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                        | OPTIONAL. Dictionary. Specifies a response function that was utilised by a deconvolution algorithm; more details below.                                                                                                               |
 
 Dictionary `"OrientationEncoding"` has the following reserved keywords:
 

From 7a123d57267759802e4433f0b34707c82d0d0223 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Wed, 1 May 2024 13:18:03 +1000
Subject: [PATCH 52/65] Diffusion model derivatives: Spelling fixes

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 0df97d43..fc8d6633 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -95,7 +95,7 @@ entity "`_param-<label>`" MUST NOT be included; e.g.:
 
 There are many mathematical bases that may be used
 in the encoding of parameters that vary as a function of orientation.
-A list of such functions supported by the specification is enuerated below,
+A list of such functions supported by the specification is enumerated below,
 accompanied by requisite information specific to each representation.
 
 For image data that encode orientation information,
@@ -169,7 +169,7 @@ see [parameter metadata](#parameter-metadata).
     1.  Orientations only
 
         Each triplet of values encodes an orientation on the unit sphere
-        (i.e. the vector norm MUST be 1.0);
+        (that is, the vector norm MUST be 1.0);
         no quantitative value is associated with each orientation.
 
     Number of image volumes is equal to (3x*N*),
@@ -216,7 +216,7 @@ see [parameter metadata](#parameter-metadata).
 
 For some models,
 it is common to export not only the best fit of the model to the empirical data,
-but multiple reaslisations of that fit taking into account image noise,
+but multiple realizations of that fit taking into account image noise,
 typically through some form of bootstrapping procedure.
 Where this occurs,
 the image data for each parameter possess an additional dimension,

From 4cf0723ab04d255273b93957181291fa260b3a11 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Tue, 14 May 2024 13:50:28 -0700
Subject: [PATCH 53/65] Apply US spelling. Addresses current codespell CI
 failure.

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fc8d6633..8b6867f8 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -40,7 +40,7 @@ that warrant explicit mention due to their consequence in how they are represent
 -   The encoding of *anisotropic* information;
     that is, quantities for which the value depends on the orientation in which it is sampled.
     Much of the detail in diffusion derivatives is therefore dedicated
-    to the definition of how such data are serialised into corresponding NIfTI images,
+    to the definition of how such data are serialized into corresponding NIfTI images,
     and how corresponding metadata is used to facilitate correct interpretation of those data.
 
 -   A diffusion model may represent the contents of each image voxel as the sum of *multiple compartments*;
@@ -268,7 +268,7 @@ Dictionary `"Model["Parameters"]"` has the following reserved keywords that may
 
 | **Key name**           | **Description**                                                                                                                                                                                                                                                                                               |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FitMethod              | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Resrved values are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
+| FitMethod              | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Reserved values are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
 | Iterations             | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                           |
 | OutlierRejectionMethod | OPTIONAL. String. Text describing any form of rejection of outlier values that was performed during fitting of the model.                                                                                                                                                                                     |
 | Samples                | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters were computed.                                                                                                                                        |
@@ -282,9 +282,9 @@ Some fields are applicable only to specific [orientation encoding types](#orient
 | ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | BootstrapAxis       | Any                                                                                        | OPTIONAL. Integer. If multiple realisations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realisations are stored.                             |
 | Description         | Any                                                                                        | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
-| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularised to not take extreme negative values, or was explicitly forbidden from taking negative values. |
+| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularized to not take extreme negative values, or was explicitly forbidden from taking negative values. |
 | OrientationEncoding | Any                                                                                        | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
-| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                        | OPTIONAL. Dictionary. Specifies a response function that was utilised by a deconvolution algorithm; more details below.                                                                                                               |
+| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                        | OPTIONAL. Dictionary. Specifies a response function that was utilized by a deconvolution algorithm; more details below.                                                                                                               |
 
 Dictionary `"OrientationEncoding"` has the following reserved keywords:
 
@@ -321,7 +321,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
     -   List of lists of floating-point values.
         One list per unique *b*-value.
         Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero.
-        If the response function utilised has a different number of non-zero zonal spherical harmonic coefficients for different *b*-values,
+        If the response function utilized has a different number of non-zero zonal spherical harmonic coefficients for different *b*-values,
         these must be padded with zeroes such that all lists contain the same number of floating-point values.
 
 ### Demonstrative examples
@@ -780,10 +780,10 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
     Notes:
 
-    -   Here the descriptors "`merged`" and "`mean`" have been utilised
+    -   Here the descriptors "`merged`" and "`mean`" have been utilized
         to distinguish between the comprehensive set of all bootstrap realisations
         and the computed mean statistics of parameters across all realisations respectively,
-        as this is the terminology utilised by the FSL software itself.
+        as this is the terminology utilized by the FSL software itself.
         These labels are not however a part of the specification.
 
     -   Care must be taken for images of greater than three dimensions

From 1317863ad7aec9beb504c47becc95cc6b4df3791 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Tue, 14 May 2024 13:53:15 -0700
Subject: [PATCH 54/65] Markdown table linting

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 8b6867f8..761e19c7 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -891,9 +891,9 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
         *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
 
-        | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | 10 | ...  |
+        | ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | 10 | ... |
         | --------------------- |--:|--:|--: |--: |--: |--: | :--: |
-        | ***N***               | 1 | 6 | 15 | 28 | 45 | 66 | ...  |
+        | ***N***               | 1 | 6 | 15 | 28 | 45 | 66 | ... |
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
@@ -902,6 +902,6 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
         *N* = 1 + (*l<sub>max</sub>* / 2)
 
-        | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | 10 | ...  |
+        | ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | 10 | ... |
         | --------------------- |--:|--:|--:|--:|--:|--: | :--: |
-        | ***N***               | 1 | 2 | 3 | 4 | 5 | 6  | ...  |
+        | ***N***               | 1 | 2 | 3 | 4 | 5 | 6  | ... |

From 77dbfbd718b8c3c380d8e630c92aea401eb37115 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Tue, 14 May 2024 13:54:28 -0700
Subject: [PATCH 55/65] Get rid of a few latin phrases (i.e., "e.g.").

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 761e19c7..703ef717 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -82,7 +82,7 @@ that warrant explicit mention due to their consequence in how they are represent
     how data across dimensions beyond the three spatial dimensions are to be interpreted.
 
 In cases where a pipeline yields only a single parameter from a model,
-entity "`_param-<label>`" MUST NOT be included; e.g.:
+entity "`_param-<label>`" MUST NOT be included; for example:
 ```Text
 <pipeline_name>/
     sub-<participant_label>/
@@ -271,7 +271,7 @@ Dictionary `"Model["Parameters"]"` has the following reserved keywords that may
 | FitMethod              | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Reserved values are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
 | Iterations             | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.                                                                                                                                                           |
 | OutlierRejectionMethod | OPTIONAL. String. Text describing any form of rejection of outlier values that was performed during fitting of the model.                                                                                                                                                                                     |
-| Samples                | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (e.g. mean, standard deviation) of those parameters were computed.                                                                                                                                        |
+| Samples                | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (such as mean, standard deviation) of those parameters were computed.                                                                                                                                        |
 
 #### Parameter metadata
 
@@ -897,7 +897,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
     -   Relationship between maximal degree of *zonal* spherical harmonic
         function (spherical harmonics function where all *m* != 0 terms are
-        assumed to be zero; used for e.g. response function definition) and
+        assumed to be zero; used for response function definition and similar) and
         number of coefficients *N*:
 
         *N* = 1 + (*l<sub>max</sub>* / 2)

From 156359ab7a994a67905b3dfffb4d16528a1e8d28 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 15 May 2024 11:22:59 +1000
Subject: [PATCH 56/65] DWI models: Define "bvec" orientation reference

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fc8d6633..1b2b3a9a 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -294,12 +294,20 @@ Dictionary `"OrientationEncoding"` has the following reserved keywords:
 | AntipodalSymmetry       | [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector), [tensor](#encoding-tensor), [amplitudes](#encoding-amp), [spherical harmonics](#encoding-sh) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                                                                                                                                                                                            |
 | EncodingAxis            | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding.                                                                                                                                                                                                                                                                |
 | FillValue               | [Scalar](#encoding-scalar), [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector)                                                                   | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when the number of discrete orientations in a given voxel is fewer than the maximal number for that image.                                                                                                                                                                                                                                              |
-| Reference               | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information.                                                                                                                                                                                                                                                   |
+| Reference               | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. String; allowed values: { `bvec`, `ijk`, `xyz` }. Defines the reference coordinate system against which orientation information is encoded (more below).                                                                                                                                                                                                                                                           |
 | SphericalHarmonicBasis  | [Spherical harmonics](#encoding-sh)                                                                                                                                        | REQUIRED for `"Type": "sh"`; MUST NOT be specified otherwise. String. Options are: { `mrtrix3`, `descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                                                                                                                                 |
 | SphericalHarmonicDegree | [Spherical harmonics](#encoding-sh)                                                                                                                                        | OPTIONAL for `"Type": "sh"`; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                       |
 | TensorRank              | [Tensor](#encoding-tensor)                                                                                                                                                 | REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2.                                                                                                                                                                                                                                                                |
 | Type                    | Any                                                                                                                                                                        | REQUIRED. String. Specifies the type of orientation information (if any) encoded in the NIfTI image. Permitted values: { `scalar`, `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `tensor`, `sh`, `amplitudes` }.                                                                                                                                                                                            |
 
+Field `"OrientationEncoding"["Reference"]` MUST contain one of the following values:
+
+| **Value** | **Interpretation**                                                                                                                                                                                                                                                            |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bvec      | The three spatial image axes; **unless** those axes form a right-handed coordinate system (that is, the 3x3 linear component of the NIfTI header transformation has a positive determinant), in which case the negative of the first axis orientation is the first reference. |
+| ijk       | The three spatial image axes define the orientation reference.                                                                                                                                                                                                                |
+| xyz       | The "real" / "scanner" space axes, which are independent of the NIfTI image header transform, define the orientation reference.                                                                                                                                               |
+
 Dictionary `"ResponseFunction"` has the following reserved keywords:
 
 | **Key name** | **Description**                                                                                                                                                                            |
@@ -634,7 +642,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
         },
         "OrientationEncoding": {
             "EncodingAxis": 3,
-            "Reference": "ijk",
+            "Reference": "bvec",
             "Type": "unit3vector"
         }
     }

From adb0e62a79f5b18cbe0761b88fda826f6a4f0770 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 15 May 2024 12:11:58 +1000
Subject: [PATCH 57/65] DWI models: Force presence of "param" entity

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fc8d6633..0192c996 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -81,16 +81,6 @@ that warrant explicit mention due to their consequence in how they are represent
     they MUST also specify requisite metadata fields regarding
     how data across dimensions beyond the three spatial dimensions are to be interpreted.
 
-In cases where a pipeline yields only a single parameter from a model,
-entity "`_param-<label>`" MUST NOT be included; e.g.:
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>]_model-<label>_dwimap.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>_dwimap.json
-```
-
 ### Orientation encoding types
 
 There are many mathematical bases that may be used
@@ -406,6 +396,10 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
         rather, it is the *diffusivity* that is the estimated parameter,
         and the *way in which the anisotropy of that parameter is encoded* is a tensor.
 
+    -   Even if image `sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`
+        were to be the only image yielded by the pipeline,
+        it is nevertheless REQUIRED to include entity "`_param-`" in those file names.
+
     -   Metadata fields relevant to the interpretation of the anisotropy of the tensor
         are *not relevant* to the scalar measures
         "`s0`" (estimated signal intensity with no diffusion weighting)

From 2ac5549f07ed0098e41f82b308f9281aa8707f82 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 15 May 2024 12:46:59 +1000
Subject: [PATCH 58/65] DWI models: add "ParameterURL" metadata field

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fc8d6633..4ee5ce77 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -284,6 +284,7 @@ Some fields are applicable only to specific [orientation encoding types](#orient
 | Description         | Any                                                                                        | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
 | NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularised to not take extreme negative values, or was explicitly forbidden from taking negative values. |
 | OrientationEncoding | Any                                                                                        | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
+| ParameterURL        | Any                                                                                        | OPTIONAL. String. URL to documentation that describes the specific model parameter that is encoded within the data file.                                                                                                              |
 | ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                        | OPTIONAL. Dictionary. Specifies a response function that was utilised by a deconvolution algorithm; more details below.                                                                                                               |
 
 Dictionary `"OrientationEncoding"` has the following reserved keywords:
@@ -393,7 +394,8 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
                 "FitMethod": "ols",
                 "OutlierRejectionmethod": "None"
             }
-        }
+        },
+        "ParameterURL": "https://doi.org/10.1002/nbm.1940080707"
     }
     ```
 
@@ -447,6 +449,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
             "SphericalHarmonicDegree": 8,
             "Type": "sh",
         },
+        "ParameterURL": "http://www.sciencedirect.com/science/article/pii/S1053811911012092",
         "ResponseFunction": {
             "Coefficients": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
                               [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],

From 3bb9da04d31b73241f73186cdf110de45a596147 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 15 May 2024 14:09:43 +1000
Subject: [PATCH 59/65] Clarify metadata fields relevance (#102)

* DWI models: Clarify metadata fields relevance

* DWI models: Typo fix

---------

Co-authored-by: Ariel Rokem <arokem@gmail.com>
---
 src/derivatives/05-diffusion-derivatives.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index fc8d6633..f51fb0e6 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -275,8 +275,15 @@ Dictionary `"Model["Parameters"]"` has the following reserved keywords that may
 
 #### Parameter metadata
 
-The following table defines reserved fields relevant to individual model parameters.
-Some fields are applicable only to specific [orientation encoding types](#orientation-encoding-types).
+The following tables define reserved fields relevant to individual model parameters.
+
+Some fields are relevant only to specific [orientation encoding types](#orientation-encoding-types):
+
+-   Where a field *is* relevant for the corresponding image,
+    designators OPTIONAL and REQUIRED within the "Description" column apply.
+
+-   Where a field is *not* relevant for the corresponding image,
+    that metadata field MUST NOT be specified.
 
 | **Key name**        | Relevant [orientation encoding types](#orientation-encoding-types)                         | **Description**                                                                                                                                                                                                                       |
 | ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

From e4df23c63bc3e9dd7432646abed083e853a4b76d Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Wed, 15 May 2024 06:54:35 -0700
Subject: [PATCH 60/65] Removes one more i.e.

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index a8df03be..c5625af5 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -856,7 +856,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
         for *maximum* spherical harmonic order *l<sub>max</sub>*.
 
-    -   Functions assumed to be real: conjugate symmetry is assumed, i.e.
+    -   Functions assumed to be real: conjugate symmetry is assumed, that is,
         *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
         conjugate.
 

From 900381c06a52606a30877d93b3c44295bb20aa48 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 16 May 2024 11:09:13 +1000
Subject: [PATCH 61/65] BEP016: Utilize filesystem macro

---
 src/derivatives/05-diffusion-derivatives.md | 155 ++++++++++++--------
 1 file changed, 90 insertions(+), 65 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index c5625af5..65b30795 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -19,15 +19,20 @@
 
 Template:
 
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>]_desc-preproc_dwi.nii[.gz]
-            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvals
-            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvecs
-            <source_keywords>[_space-<space>]_desc-preproc_dwi.json
-```
+{{ MACROS___make_filetree_example(
+  {
+    "<pipeline_name>": {
+      "sub-<participant_label>": {
+        "dwi": {
+          "<source_keywords>[_space-<space>]_desc-preproc_dwi.bval": "",
+          "<source_keywords>[_space-<space>]_desc-preproc_dwi.bvec": "",
+          "<source_keywords>[_space-<space>]_desc-preproc_dwi.json": "",
+          "<source_keywords>[_space-<space>]_desc-preproc_dwi.nii[.gz]": "",
+        },
+      },
+    },
+  }
+) }}
 
 ## Diffusion models
 
@@ -52,17 +57,22 @@ that warrant explicit mention due to their consequence in how they are represent
 
 ### Basic filesystem structure
 
-```Text
-<pipeline_name>/
-    sub-<participant_label>/
-        dwi/
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.json
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.json
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.nii[.gz]
-            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.json
-```
+{{ MACROS___make_filetree_example(
+  {
+    "<pipeline_name>": {
+      "sub-<participant_label>": {
+        "dwi": {
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.nii[.gz]": "",
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.json": "",
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.nii[.gz]": "",
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.json": "",
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.nii[.gz]": "",
+          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.json": "",
+        },
+      },
+    },
+  }
+) }}
 
 -   Files "`<source_keywords>_model-<label>_param-<label*>_dwimap.nii[.gz]`"
     provide image data encoding the different parameters that may be estimated by the model.
@@ -326,17 +336,22 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
 -   A basic Diffusion Tensor fit:
 
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-tensor_param-diffusivity_dwimap.nii.gz
-                sub-01_model-tensor_param-diffusivity_dwimap.json
-                sub-01_model-tensor_param-s0_dwimap.nii.gz
-                sub-01_model-tensor_param-s0_dwimap.json
-                sub-01_model-tensor_param-fa_dwimap.nii.gz
-                sub-01_model-tensor_param-fa_dwimap.json
-    ```
+    {{ MACROS___make_filetree_example(
+      {
+        "dti_pipeline": {
+          "sub-01": {
+            "dwi": {
+              "sub-01_model-tensor_param-diffusivity_dwimap.nii.gz": "",
+              "sub-01_model-tensor_param-diffusivity_dwimap.json": "",
+              "sub-01_model-tensor_param-s0_dwimap.nii.gz": "",
+              "sub-01_model-tensor_param-s0_dwimap.json": "",
+              "sub-01_model-tensor_param-fa_dwimap.nii.gz": "",
+              "sub-01_model-tensor_param-fa_dwimap.json": "",
+            },
+          },
+        },
+      }
+    ) }}
 
     Dimensions of NIfTI image "`sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K*x6 ([symmetric rank 2 tensor image](#encoding-tensor))
     Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
@@ -417,17 +432,22 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
 -   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
 
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-csd_param-wm_dwimap.nii.gz
-                sub-01_model-csd_param-wm_dwimap.json
-                sub-01_model-csd_param-gm_dwimap.nii.gz
-                sub-01_model-csd_param-gm_dwimap.json
-                sub-01_model-csd_param-csf_dwimap.nii.gz
-                sub-01_model-csd_param-csf_dwimap.json
-    ```
+    {{ MACROS___make_filetree_example(
+      {
+        "msmtcsd_pipeline": {
+          "sub-01": {
+            "dwi": {
+              "sub-01_model-csd_param-wm_dwimap.nii.gz": "",
+              "sub-01_model-csd_param-wm_dwimap.json": "",
+              "sub-01_model-csd_param-gm_dwimap.nii.gz": "",
+              "sub-01_model-csd_param-gm_dwimap.json": "",
+              "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
+              "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
+            },
+          },
+        },
+      }
+    ) }}
 
     Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
     Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
@@ -537,29 +557,34 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 -   An FSL `bedpostx` Ball-And-Sticks fit
     (including both mean parameters and bootstrap realisations):
 
-    ```Text
-    my_diffusion_pipeline/
-        sub-01/
-            dwi/
-                sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-s0_dwimap.json
-                sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-polar_dwimap.json
-                sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-vector_dwimap.json
-                sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-vf_dwimap.json
-                sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-vfsum_dwimap.json
-                sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json
-                sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz
-                sub-01_model-bs_desc-mean_param-dstd_dwimap.json
-                sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz
-                sub-01_model-bs_desc-merged_param-polar_dwimap.json
-                sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz
-                sub-01_model-bs_desc-merged_param-vf_dwimap.json
-    ```
+    {{ MACROS___make_filetree_example(
+      {
+        "bedpostx_pipeline": {
+          "sub-01": {
+            "dwi": {
+              "sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-s0_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-polar_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-vector_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-vf_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-vfsum_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json": "",
+              "sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-mean_param-dstd_dwimap.json": "",
+              "sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-merged_param-polar_dwimap.json": "",
+              "sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz": "",
+              "sub-01_model-bs_desc-merged_param-vf_dwimap.json": "",
+            },
+          },
+        },
+      }
+    ) }}
 
     Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
     Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*) ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel)

From c531a0a79aa22c162eebf462b2cbab235f55bede Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 16 May 2024 11:11:27 +1000
Subject: [PATCH 62/65] BEP016: Reformat demonstrative examples

---
 src/derivatives/05-diffusion-derivatives.md | 960 ++++++++++----------
 1 file changed, 481 insertions(+), 479 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 65b30795..95b21559 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -334,534 +334,536 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
 ### Demonstrative examples
 
--   A basic Diffusion Tensor fit:
-
-    {{ MACROS___make_filetree_example(
-      {
-        "dti_pipeline": {
-          "sub-01": {
-            "dwi": {
-              "sub-01_model-tensor_param-diffusivity_dwimap.nii.gz": "",
-              "sub-01_model-tensor_param-diffusivity_dwimap.json": "",
-              "sub-01_model-tensor_param-s0_dwimap.nii.gz": "",
-              "sub-01_model-tensor_param-s0_dwimap.json": "",
-              "sub-01_model-tensor_param-fa_dwimap.nii.gz": "",
-              "sub-01_model-tensor_param-fa_dwimap.json": "",
-            },
-          },
-        },
-      }
-    ) }}
-
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K*x6 ([symmetric rank 2 tensor image](#encoding-tensor))
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-    Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-
-    Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
+#### A basic Diffusion Tensor fit
 
-    ```JSON
+{{ MACROS___make_filetree_example(
     {
-        "Description": "Diffusion Coefficient, encoded as a tensor representation",
-        "Model": {
-            "Description": "Diffusion Tensor",
-            "Parameters": {
-                "FitMethod": "ols",
-                "OutlierRejectionMethod": "None"
-            }
+    "dti_pipeline": {
+        "sub-01": {
+        "dwi": {
+            "sub-01_model-tensor_param-diffusivity_dwimap.nii.gz": "",
+            "sub-01_model-tensor_param-diffusivity_dwimap.json": "",
+            "sub-01_model-tensor_param-s0_dwimap.nii.gz": "",
+            "sub-01_model-tensor_param-s0_dwimap.json": "",
+            "sub-01_model-tensor_param-fa_dwimap.nii.gz": "",
+            "sub-01_model-tensor_param-fa_dwimap.json": "",
         },
-        "OrientationEncoding": {
-            "AntipodalSymmetry": true,
-            "EncodingAxis": 3,
-            "Reference": "xyz",
-            "TensorRank": 2,
-            "Type": "tensor"
         },
-        "Units": "mm^2/s"
+    },
     }
-    ```
+) }}
 
-    Contents of file `sub-01_model-tensor_param-s0_dwimap.json`:
+Dimensions of NIfTI image "`sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K*x6 ([symmetric rank 2 tensor image](#encoding-tensor))
+Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
 
-    ```JSON
-    {
-        "Description": "Estimated signal intensity with no diffusion weighting, ie. S0",
-        "Model": {
-            "Description": "Diffusion Tensor",
-            "Parameters": {
-                "FitMethod": "ols",
-                "OutlierRejectionmethod": "None"
-            }
+Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
+
+```JSON
+{
+    "Description": "Diffusion Coefficient, encoded as a tensor representation",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionMethod": "None"
+        }
+    },
+    "OrientationEncoding": {
+        "AntipodalSymmetry": true,
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "TensorRank": 2,
+        "Type": "tensor"
+    },
+    "Units": "mm^2/s"
+}
+```
+
+Contents of file `sub-01_model-tensor_param-s0_dwimap.json`:
+
+```JSON
+{
+    "Description": "Estimated signal intensity with no diffusion weighting, ie. S0",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionmethod": "None"
         }
     }
-    ```
+}
+```
+
+Contents of file `sub-01_model-tensor_param-fa_dwimap.json`:
+
+```JSON
+{
+    "Description": "Fractional Anisotropy",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionmethod": "None"
+        }
+    },
+    "ParameterURL": "https://doi.org/10.1002/nbm.1940080707"
+}
+```
 
-    Contents of file `sub-01_model-tensor_param-fa_dwimap.json`:
+Notes:
 
-    ```JSON
-    {
-        "Description": "Fractional Anisotropy",
-        "Model": {
-            "Description": "Diffusion Tensor",
-            "Parameters": {
-                "FitMethod": "ols",
-                "OutlierRejectionmethod": "None"
-            }
-        },
-        "ParameterURL": "https://doi.org/10.1002/nbm.1940080707"
-    }
-    ```
-
-    Notes:
-
-    -   "The diffusion tensor" intrinsically is a mathematical model of how
-        the diffusivity is estimated to vary as a function of orientation.
-        As such, within this model,
-        it is not the *parameter* that is a tensor;
-        rather, it is the *diffusivity* that is the estimated parameter,
-        and the *way in which the anisotropy of that parameter is encoded* is a tensor.
-
-    -   Even if image `sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`
-        were to be the only image yielded by the pipeline,
-        it is nevertheless REQUIRED to include entity "`_param-`" in those file names.
-
-    -   Metadata fields relevant to the interpretation of the anisotropy of the tensor
-        are *not relevant* to the scalar measures
-        "`s0`" (estimated signal intensity with no diffusion weighting)
-        or "`fa`" (Fractional Anisotropy).
-        Those fields therefore MUST be omitted from the corresponding sidecar JSONs.
-
--   A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
-
-    {{ MACROS___make_filetree_example(
-      {
-        "msmtcsd_pipeline": {
-          "sub-01": {
-            "dwi": {
-              "sub-01_model-csd_param-wm_dwimap.nii.gz": "",
-              "sub-01_model-csd_param-wm_dwimap.json": "",
-              "sub-01_model-csd_param-gm_dwimap.nii.gz": "",
-              "sub-01_model-csd_param-gm_dwimap.json": "",
-              "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
-              "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
-            },
-          },
-        },
-      }
-    ) }}
+-   "The diffusion tensor" intrinsically is a mathematical model of how
+    the diffusivity is estimated to vary as a function of orientation.
+    As such, within this model,
+    it is not the *parameter* that is a tensor;
+    rather, it is the *diffusivity* that is the estimated parameter,
+    and the *way in which the anisotropy of that parameter is encoded* is a tensor.
 
-    Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
-    Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
-    Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
+-   Even if image `sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`
+    were to be the only image yielded by the pipeline,
+    it is nevertheless REQUIRED to include entity "`_param-`" in those file names.
 
-    Contents of JSON file "`sub-01_model-csd_param-wm_model.json`":
+-   Metadata fields relevant to the interpretation of the anisotropy of the tensor
+    are *not relevant* to the scalar measures
+    "`s0`" (estimated signal intensity with no diffusion weighting)
+    or "`fa`" (Fractional Anisotropy).
+    Those fields therefore MUST be omitted from the corresponding sidecar JSONs.
 
-    ```JSON
+#### A multi-shell, multi-tissue Constrained Spherical Deconvolution fit
+
+{{ MACROS___make_filetree_example(
     {
-        "Model": {
-            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    "msmtcsd_pipeline": {
+        "sub-01": {
+        "dwi": {
+            "sub-01_model-csd_param-wm_dwimap.nii.gz": "",
+            "sub-01_model-csd_param-wm_dwimap.json": "",
+            "sub-01_model-csd_param-gm_dwimap.nii.gz": "",
+            "sub-01_model-csd_param-gm_dwimap.json": "",
+            "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
+            "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
         },
-        "Description": "White matter",
-        "NonNegativity": "constrained",
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "Reference": "xyz",
-            "SphericalHarmonicBasis": "MRtrix3",
-            "SphericalHarmonicDegree": 8,
-            "Type": "sh",
         },
-        "ParameterURL": "http://www.sciencedirect.com/science/article/pii/S1053811911012092",
-        "ResponseFunction": {
-            "Coefficients": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
-                              [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
-                              [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
-                              [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
-            "Type": "zsh"
-        }
+    },
     }
-    ```
+) }}
 
-    Contents of JSON file "`sub-01_model-csd_param-gm_dwimap.json`":
+Dimensions of NIfTI image "`sub-01_model-csd_param-wm_model.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
+Dimensions of NIfTI image "`sub-01_model-csd_param-gm_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
+Dimensions of NIfTI image "`sub-01_model-csd_param-csf_model.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
 
-    ```JSON
-    {
-        "Model": {
-            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
-        },
-        "Description": "Gray matter",
-        "NonNegativity": "constrained",
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "Reference": "xyz",
-            "SphericalHarmonicBasis": "MRtrix3",
-            "SphericalHarmonicDegree": 0,
-            "Type": "sh",
-        },
-        "ResponseFunction": {
-            "Coefficients": [ [ 1041.0 ],
-                              [ 436.6 ],
-                              [ 224.9 ],
-                              [ 128.8 ] ],
-            "Type": "zsh"
-        }
+Contents of JSON file "`sub-01_model-csd_param-wm_model.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "White matter",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 8,
+        "Type": "sh",
+    },
+    "ParameterURL": "http://www.sciencedirect.com/science/article/pii/S1053811911012092",
+    "ResponseFunction": {
+        "Coefficients": [ [ 600.2 0.0 0.0 0.0 0.0 0.0 ],
+                            [ 296.3 -115.2 24.7 -4.4 -0.5 1.8 ],
+                            [ 199.8 -111.3 41.8 -10.2 2.1 -0.7 ],
+                            [ 158.3 -98.7 48.4 -17.1 4.5 -1.4 ] ],
+        "Type": "zsh"
     }
-    ```
+}
+```
 
-    Contents of JSON file "`sub-01_model-csd_param-csf_dwimap.json`":
+Contents of JSON file "`sub-01_model-csd_param-gm_dwimap.json`":
 
-    ```JSON
-    {
-        "Model": {
-            "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
-            "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
-        },
-        "Description": "Cerebro-spinal fluid",
-        "NonNegativity": "constrained",
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "Reference": "xyz",
-            "SphericalHarmonicBasis": "MRtrix3",
-            "SphericalHarmonicDegree": 0,
-            "Type": "sh"
-        },
-        "ResponseFunction": {
-            "Coefficients": [ [ 3544.90770181 ],
-                              [ 134.441453035 ],
-                              [ 32.0826839826 ],
-                              [ 29.3674604452 ] ],
-            "Type": "zsh"
-        }
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "Gray matter",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 0,
+        "Type": "sh",
+    },
+    "ResponseFunction": {
+        "Coefficients": [ [ 1041.0 ],
+                            [ 436.6 ],
+                            [ 224.9 ],
+                            [ 128.8 ] ],
+        "Type": "zsh"
     }
-    ```
-
-    Notes:
-
-    -   In this example,
-        the gray matter and CSF compartments are specified in the spherical harmonics basis
-        with maximal spherical harmonic degrees of zero,
-        even though each image only contains a single volume
-        and could therefore be interpreted as simply scalar parameters.
-        This is recommended in this instance
-        given that the spherical harmonic basis imposes a $\sqrt(4\pi)$ scaling
-        that should be taken into account if comparing the values of these parameters
-        with the *l*=0 term of the white matter ODF.
-
-    -   The response functions for GM and CSF have a maximal zonal spherical harmonic degree of zero,
-        such that only one coefficient is required for each unique *b*-value shell.
-        It is however nevertheless vital that these data be provided as a list of lists of floats,
-        where the length of each list is one;
-        storing these values as a list of floats would be erroneously interpreted
-        as coefficients of different zonal spherical harmonic degrees for a single *b*-value shell.
-
--   An FSL `bedpostx` Ball-And-Sticks fit
-    (including both mean parameters and bootstrap realisations):
-
-    {{ MACROS___make_filetree_example(
-      {
-        "bedpostx_pipeline": {
-          "sub-01": {
-            "dwi": {
-              "sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-s0_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-polar_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-vector_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-vf_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-vfsum_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json": "",
-              "sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-mean_param-dstd_dwimap.json": "",
-              "sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-merged_param-polar_dwimap.json": "",
-              "sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz": "",
-              "sub-01_model-bs_desc-merged_param-vf_dwimap.json": "",
-            },
-          },
-        },
-      }
-    ) }}
-
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*) ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel)
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz`": *I*x*J*x*K*x(*3*x*N*) ([3-vectors](#encoding-3vectors), unit norm; *N* orientations per voxel)
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N* ([scalar](#encoding-scalar); *N* values per voxel)
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*)x*R* ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel; *R* bootstrap realisations)
-    Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N*x*R* ([scalar](#encoding-scalar); *N* values per voxel; *R* bootstrap realisations)
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-s0_dwimap.json`":
-
-    ```JSON
-    {
-        "Description": "Estimated signal intensity with no diffusion weighting, ie. S0; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
-        }
+}
+```
+
+Contents of JSON file "`sub-01_model-csd_param-csf_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "Cerebro-spinal fluid",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 0,
+        "Type": "sh"
+    },
+    "ResponseFunction": {
+        "Coefficients": [ [ 3544.90770181 ],
+                            [ 134.441453035 ],
+                            [ 32.0826839826 ],
+                            [ 29.3674604452 ] ],
+        "Type": "zsh"
     }
-    ```
+}
+```
+
+Notes:
 
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-polar_dwimap.json`":
+-   In this example,
+    the gray matter and CSF compartments are specified in the spherical harmonics basis
+    with maximal spherical harmonic degrees of zero,
+    even though each image only contains a single volume
+    and could therefore be interpreted as simply scalar parameters.
+    This is recommended in this instance
+    given that the spherical harmonic basis imposes a $\sqrt(4\pi)$ scaling
+    that should be taken into account if comparing the values of these parameters
+    with the *l*=0 term of the white matter ODF.
 
-    ```JSON
+-   The response functions for GM and CSF have a maximal zonal spherical harmonic degree of zero,
+    such that only one coefficient is required for each unique *b*-value shell.
+    It is however nevertheless vital that these data be provided as a list of lists of floats,
+    where the length of each list is one;
+    storing these values as a list of floats would be erroneously interpreted
+    as coefficients of different zonal spherical harmonic degrees for a single *b*-value shell.
+
+#### An FSL `bedpostx` Ball-And-Sticks fit
+
+This example includes both bootstrap realisations of the model fit,
+and the aggregated means of those parameters across realisations.
+
+{{ MACROS___make_filetree_example(
     {
-        "Description": "Fibre orientations encoded using polar angles; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+    "bedpostx_pipeline": {
+        "sub-01": {
+        "dwi": {
+            "sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-s0_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-polar_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-vector_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-vf_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-vfsum_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json": "",
+            "sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-mean_param-dstd_dwimap.json": "",
+            "sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-merged_param-polar_dwimap.json": "",
+            "sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz": "",
+            "sub-01_model-bs_desc-merged_param-vf_dwimap.json": "",
         },
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "Reference": "ijk",
-            "Type": "unitspherical"
-        }
+        },
+    },
     }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vector_dwimap.json`":
+) }}
 
-    ```JSON
-    {
-        "Description": "Fibre orientations encoded using 3-vectors; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*) ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel)
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz`": *I*x*J*x*K*x(*3*x*N*) ([3-vectors](#encoding-3vectors), unit norm; *N* orientations per voxel)
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N* ([scalar](#encoding-scalar); *N* values per voxel)
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*)x*R* ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel; *R* bootstrap realisations)
+Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N*x*R* ([scalar](#encoding-scalar); *N* values per voxel; *R* bootstrap realisations)
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-s0_dwimap.json`":
+
+```JSON
+{
+    "Description": "Estimated signal intensity with no diffusion weighting, ie. S0; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "Reference": "ijk",
-            "Type": "unit3vector"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
         }
     }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vf_dwimap.json`":
-
-    ```JSON
-    {
-        "Description": "Volume fractions of stick components; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-polar_dwimap.json`":
+
+```JSON
+{
+    "Description": "Fibre orientations encoded using polar angles; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "OrientationEncoding": {
-            "Type": "scalar"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
         }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "ijk",
+        "Type": "unitspherical"
     }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.json`":
-
-    ```JSON
-    {
-        "Description": "Sum of volume fractions of stick components; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vector_dwimap.json`":
+
+```JSON
+{
+    "Description": "Fibre orientations encoded using 3-vectors; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
         }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "ijk",
+        "Type": "unit3vector"
     }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json`":
-
-    ```JSON
-    {
-        "Description": "Diffusivity; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vf_dwimap.json`":
+
+```JSON
+{
+    "Description": "Volume fractions of stick components; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "Units": "mm^2/s"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "Type": "scalar"
     }
-    ```
-
-    Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
-
-    ```JSON
-    {
-        "Description": "Diffusivity variance parameter; mean across bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.json`":
+
+```JSON
+{
+    "Description": "Sum of volume fractions of stick components; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "Units": "TODO"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
     }
-
-    Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
-
-    ```JSON
-    {
-        "BootstrapAxis": 4,
-        "Description": "Fibre orientations encoded using polar angles; concatenated bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json`":
+
+```JSON
+{
+    "Description": "Diffusivity; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "Units": "mm^2/s"
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
+
+```JSON
+{
+    "Description": "Diffusivity variance parameter; mean across bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "Units": "TODO"
+}
+
+Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
+
+```JSON
+{
+    "BootstrapAxis": 4,
+    "Description": "Fibre orientations encoded using polar angles; concatenated bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "OrientationEncoding": {
-            "EncodingAxis": 3,
-            "ReferenceAxes": "ijk",
-            "Type": "unitspherical"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
         }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "ReferenceAxes": "ijk",
+        "Type": "unitspherical"
     }
-
-    Contents of JSON file "`sub-01_model-bs_desc-merged_param-vf_dwimap.json`":
-
-    ```JSON
-    {
-        "BootstrapAxis": 4,
-        "Description": "Volume fractions of stick components; concatenated bootstrap realisations",
-        "Model": {
-            "Description": "Ball-And-Sticks model using FSL bedpostx",
-            "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
-            "Parameters": {
-                "ARDFudgeFactor": 1.0,
-                "Fibers": 3
-            },
-            "BootstrapParameters": {
-                "Burnin": 1000,
-                "Jumps": 1250,
-                "SampleEvery": 25
-            }
+}
+
+Contents of JSON file "`sub-01_model-bs_desc-merged_param-vf_dwimap.json`":
+
+```JSON
+{
+    "BootstrapAxis": 4,
+    "Description": "Volume fractions of stick components; concatenated bootstrap realisations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
         },
-        "OrientationEncoding": {
-            "Type": "scalar"
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
         }
+    },
+    "OrientationEncoding": {
+        "Type": "scalar"
     }
-
-    Notes:
-
-    -   Here the descriptors "`merged`" and "`mean`" have been utilized
-        to distinguish between the comprehensive set of all bootstrap realisations
-        and the computed mean statistics of parameters across all realisations respectively,
-        as this is the terminology utilized by the FSL software itself.
-        These labels are not however a part of the specification.
-
-    -   Care must be taken for images of greater than three dimensions
-        where additional dimensions do *not* encode anisotropy information:
-
-        -   In image `"*_desc-mean*_param-vf_*"`,
-            the fourth image axis encodes scalar information across stick components.
-            Since this is *not* coefficients in some orientation encoding,
-            but the image possesses more than three axes,
-            field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
-
-        -   Image `"*_param-vfsum_*"`is a three-dimensional image,
-            and therefore the fact that it encodes a scalar parameter
-            can be robustly inferred without reference to metadata information.
-
-        -   In image `"sub-01_model-bs_desc-merged_param-vf_dwimap.json"`,
-            there are two extra image dimensions beyond the three spatial dimensions:
-            the fourth image axis encodes across the multiple stick components per voxel,
-            and the fifth axis encodes realisations across bootstraps.
-            it is therefore necessary to explicitly specify
-            that the parameter being encoded in the data,
-            being the volume fractions of individual stick components,
-            do not have any anisotropy,
-            and therefore field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
-
-    -   TODO CONFIRM WHETHER WE WANT TO ENFORCE THIS OR INCLUDE EXPLICIT METADATA FIELDS
-        THAT INDICATE THE AXIS / AXES OF DIRECTION ENCODING VS. BOOTSTRAP REALISATIONS
-
-    -   TODO DISCUSS
-        The example presented here is not necessarily a unique solution
-        for the storage of the outcomes of the FSL `bedpostx` command as BIDS Derivatives:
-
-        -   WOULD SPLITTING STICK COMPONENTS ACROSS NIFTIS
-            REQUIRE A NEW ENTITY BY WHICH TO INDEX THEM?
-            OR JUST GIVE THEM EG. `_param-spherical1`, `_param-spherical2`?
-
-        -   While the FSL `bedpostx` command yields the fibre orientation for each individual stick
-            as polar angles within separate NIfTI images,
-            for BIDS it is RECOMMENDED that such orientation information be encoded
-            either as [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector).
-
-        -   Given that it is possible to encode a scalar parameter
-            into either [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector) encodings,
-            it is possible to store an image that encodes,
-            for each stick component,
-            both volume fraction and orientation.
-            It is however RECOMMENDED to encode this information in separate files,
-            given that in the more general case there may be multiple scalar parameters
-            individually attributed to each component.
+}
+
+Notes:
+
+-   Here the descriptors "`merged`" and "`mean`" have been utilized
+    to distinguish between the comprehensive set of all bootstrap realisations
+    and the computed mean statistics of parameters across all realisations respectively,
+    as this is the terminology utilized by the FSL software itself.
+    These labels are not however a part of the specification.
+
+-   Care must be taken for images of greater than three dimensions
+    where additional dimensions do *not* encode anisotropy information:
+
+    -   In image `"*_desc-mean*_param-vf_*"`,
+        the fourth image axis encodes scalar information across stick components.
+        Since this is *not* coefficients in some orientation encoding,
+        but the image possesses more than three axes,
+        field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+    -   Image `"*_param-vfsum_*"`is a three-dimensional image,
+        and therefore the fact that it encodes a scalar parameter
+        can be robustly inferred without reference to metadata information.
+
+    -   In image `"sub-01_model-bs_desc-merged_param-vf_dwimap.json"`,
+        there are two extra image dimensions beyond the three spatial dimensions:
+        the fourth image axis encodes across the multiple stick components per voxel,
+        and the fifth axis encodes realisations across bootstraps.
+        it is therefore necessary to explicitly specify
+        that the parameter being encoded in the data,
+        being the volume fractions of individual stick components,
+        do not have any anisotropy,
+        and therefore field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+-   TODO CONFIRM WHETHER WE WANT TO ENFORCE THIS OR INCLUDE EXPLICIT METADATA FIELDS
+    THAT INDICATE THE AXIS / AXES OF DIRECTION ENCODING VS. BOOTSTRAP REALISATIONS
+
+-   TODO DISCUSS
+    The example presented here is not necessarily a unique solution
+    for the storage of the outcomes of the FSL `bedpostx` command as BIDS Derivatives:
+
+    -   WOULD SPLITTING STICK COMPONENTS ACROSS NIFTIS
+        REQUIRE A NEW ENTITY BY WHICH TO INDEX THEM?
+        OR JUST GIVE THEM EG. `_param-spherical1`, `_param-spherical2`?
+
+    -   While the FSL `bedpostx` command yields the fibre orientation for each individual stick
+        as polar angles within separate NIfTI images,
+        for BIDS it is RECOMMENDED that such orientation information be encoded
+        either as [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector).
+
+    -   Given that it is possible to encode a scalar parameter
+        into either [spherical coordinates](#encoding-spherical) or [3-vectors](#encoding-3vector) encodings,
+        it is possible to store an image that encodes,
+        for each stick component,
+        both volume fraction and orientation.
+        It is however RECOMMENDED to encode this information in separate files,
+        given that in the more general case there may be multiple scalar parameters
+        individually attributed to each component.
 
 ### Appendix
 

From 9cb1e096fe9cd3ecd0d067cf4c8f4c2c605d2828 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 17 May 2024 10:04:32 +1000
Subject: [PATCH 63/65] BEP016: Don't use filesystem macros for templates

---
 src/derivatives/05-diffusion-derivatives.md | 52 ++++++++-------------
 1 file changed, 20 insertions(+), 32 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 95b21559..8adf5130 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -17,22 +17,15 @@
 -   As per [common data types](02-common-data-types.md) for derivative data, a
     JSON sidecar file is REQUIRED due to the REQUIRED `SkullStripped` field.
 
-Template:
-
-{{ MACROS___make_filetree_example(
-  {
-    "<pipeline_name>": {
-      "sub-<participant_label>": {
-        "dwi": {
-          "<source_keywords>[_space-<space>]_desc-preproc_dwi.bval": "",
-          "<source_keywords>[_space-<space>]_desc-preproc_dwi.bvec": "",
-          "<source_keywords>[_space-<space>]_desc-preproc_dwi.json": "",
-          "<source_keywords>[_space-<space>]_desc-preproc_dwi.nii[.gz]": "",
-        },
-      },
-    },
-  }
-) }}
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.nii[.gz]
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvals
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.bvecs
+            <source_keywords>[_space-<space>]_desc-preproc_dwi.json
+```
 
 ## Diffusion models
 
@@ -57,22 +50,17 @@ that warrant explicit mention due to their consequence in how they are represent
 
 ### Basic filesystem structure
 
-{{ MACROS___make_filetree_example(
-  {
-    "<pipeline_name>": {
-      "sub-<participant_label>": {
-        "dwi": {
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.nii[.gz]": "",
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.json": "",
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.nii[.gz]": "",
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.json": "",
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.nii[.gz]": "",
-          "<source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.json": "",
-        },
-      },
-    },
-  }
-) }}
+```Text
+<pipeline_name>/
+    sub-<participant_label>/
+        dwi/
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label1>_dwimap.json
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label2>_dwimap.json
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.nii[.gz]
+            <source_keywords>[_space-<space>]_model-<label>[_desc-<desc>]_param-<label3>_dwimap.json
+```
 
 -   Files "`<source_keywords>_model-<label>_param-<label*>_dwimap.nii[.gz]`"
     provide image data encoding the different parameters that may be estimated by the model.

From f115ec41deba0e5d8ffc6fda84a2162b779f5382 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Fri, 17 May 2024 10:08:09 +1000
Subject: [PATCH 64/65] BEP016: Comment filesystem macros

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

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 8adf5130..f059ac21 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -324,6 +324,10 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
 
 #### A basic Diffusion Tensor fit
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "dti_pipeline": {
@@ -420,6 +424,10 @@ Notes:
 
 #### A multi-shell, multi-tissue Constrained Spherical Deconvolution fit
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "msmtcsd_pipeline": {
@@ -547,6 +555,10 @@ Notes:
 This example includes both bootstrap realisations of the model fit,
 and the aggregated means of those parameters across realisations.
 
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
 {{ MACROS___make_filetree_example(
     {
     "bedpostx_pipeline": {

From b093ac12dc63dab7f6678770b381e1616555f01a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 5 Jun 2024 23:51:31 +1000
Subject: [PATCH 65/65] DWI models: Update bvec reference

- FSL bedpostx command fibre orientations stored as spherical coordinates are confirmed to use the "bvec" reference frame.
- Enforcing azimuth angle to obey the right hand rule about the zenith axis would necessitate direct modification of image intensities from bedpostx outputs to store. Therefore it would be preferable to instead define the sign of the azimuth angle based on the direction of the second reference axis.
Closes #95.
Closes #94.
---
 src/derivatives/05-diffusion-derivatives.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/derivatives/05-diffusion-derivatives.md b/src/derivatives/05-diffusion-derivatives.md
index 1b2b3a9a..04842f81 100644
--- a/src/derivatives/05-diffusion-derivatives.md
+++ b/src/derivatives/05-diffusion-derivatives.md
@@ -139,7 +139,7 @@ see [parameter metadata](#parameter-metadata).
             orthogonal to the zenith direction,
             with value of 0.0 corresponding to the *first* reference axis
             (see [parameter metadata](#parameter-metadata)),
-            increasing according to the right-hand rule about the zenith direction.
+            increasing toward the positive direction of the *second* reference axis.
 
         Number of image volumes is equal to (3x*N*),
         where *N* is the maximum number of discrete orientations in any voxel in the image.
@@ -616,7 +616,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
         },
         "OrientationEncoding": {
             "EncodingAxis": 3,
-            "Reference": "ijk",
+            "Reference": "bvec",
             "Type": "unitspherical"
         }
     }
@@ -757,7 +757,7 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
         },
         "OrientationEncoding": {
             "EncodingAxis": 3,
-            "ReferenceAxes": "ijk",
+            "ReferenceAxes": "bvec",
             "Type": "unitspherical"
         }
     }