diff --git a/src/05-derivatives/05-diffusion-derivatives.md b/src/05-derivatives/05-diffusion-derivatives.md
index 1c4047a8..a963967e 100644
--- a/src/05-derivatives/05-diffusion-derivatives.md
+++ b/src/05-derivatives/05-diffusion-derivatives.md
@@ -1,6 +1,6 @@
# 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
@@ -18,312 +18,720 @@ 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](#paramdef-input) parameters required in order to
+ define / constrain the model;
-The following is a general example of naming convention:
+- 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.
+
+### 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. *Input* model parameter:
+
+ Value or non-numerical setting that influences the conformation
+ of the diffusion model to the empirical diffusion-weighted data.
+
+1. *Intrinsic* model parameter:
+
+ Value that is the direct result of fitting the diffusion model to the
+ empirical diffusion-weighted data.
+
+1. *Extrinsic* model parameter:
+
+ 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;
+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
/
sub-/
dwi/
- [_space-][_desc-]_model-[_parameter-]_diffmodel.nii[.gz]
- [_space-][_desc-]_model-_diffmodel.json
+ [_space-][_desc-]_parameter-_.nii[.gz]
+ [_space-][_desc-]_parameter-_.nii[.gz]
+ [_space-][_desc-]_.json
+
+ [[_space-][_desc-]_parameter-_.nii[.gz]]
+ [[_space-][_desc-]_parameter-_.json]
+ [[_space-][_desc-]_parameter-_.nii[.gz]]
+ [[_space-][_desc-]_parameter-_.json]
```
-The following models are codified and should be used in the `model-`
-field. If a new model is used, common sense should be used to derive a name
-following the BIDS standard, and should ideally be integrated in a follow-up
-version of the specification.
-
-| Model label | Name & citation | Description |
-| ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DTI` | Diffusion tensor imaging (Basser et al. 1994) | 4D image with Dxx , Dxy , Dxz , Dyy , Dyz , Dzz ; the 6 unique parameters of the diffusion tensor. |
-| `DKI` | Diffusion kurtosis imaging (Jensen et al., 2005) | 4D image with Dxx , Dxy , Dxz , Dyy , Dyz , Dzz , Wxxxx , Wyyyy , Wzzzz , Wxxxy , Wxxxz , Wxyyy , Wyyyz , Wxzzz , Wyzzz , Wxxyy , Wxxzz , Wyyzz , Wxxyz , Wxyyz , Wxyzz ; Where D is the diffusion tensor and W is the kurtosis tensor. |
-| `WMTI` | White matter tract integrity (Fieremans et al., 2011) | 4D image with Dxx , Dxy , Dxz , Dyy , Dyz , Dzz , Wxxxx , Wyyyy , Wzzzz , Wxxxy , Wxxxz , Wxyyy , Wyyyz , Wxzzz , Wyzzz , Wxxyy , Wxxzz , Wyyzz , Wxxyz , Wxyyz , Wxyzz , Dhxx , Dhxy , Dhxz , Dhyy , Dhyz , Dhzz , Drxx , Drxy , Drxz , Dryy , Dryz , Drzz , AWF; where D is the diffusion tensor, W is the kurtosis tensor, AWF is the additional axonal water fraction parameter |
-| `CSD` | Constrained Spherical Deconvolution (Tournier et al. 2007; Descoteaux et al. 2009) | 4D image with spherical harmonic (SH) coefficients (number of volumes and their ordering depends on the model maximal degree and basis set, specified in the sidecar) |
-| `NODDI` | Neurite Orientation Dispersion and Density Imaging (Zhang et al. 2012, Daducci et al., 2015) | Three 3D images, with 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 Dcxx , Dcxy , Dcxz , Dcyy , Dcyz , Dczz , 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 fi , thi , phi (volume fraction, polar angle, azimuthal angle) for up to 3 fibres, D, Dstd (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"}
+- Field "``" 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.
-- `BEDPOSTX` :
+- Files "`[_space-][_desc-]_parameter-_.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.:
- - `NFibers` : value
- - `Fudge` : value
- - `BurnIn` : value
- - `NJumps` : value
- - `SampleEvery` : value
- - `Model` : {`monoexponential`,`multiexponentialStick`,`multiexponentialZeppelin`}
+ ```Text
+ /
+ sub-/
+ dwi/
+ [_space-][_desc-]_parameter-all_.nii[.gz]
+ [_space-][_desc-]_.json
+ ```
-Examples:
+- File "`[_space-][_desc-]_.json`"
+ provides basic model information and [input](#paramdef-input)
+ model parameters.
-A Diffusion Tensor fit:
+- OPTIONAL images "`[_space-][_desc-]_parameter-_.nii[.gz]`"
+ may be defined, in order to provide additional [extrinsic](#paramdef-extrinsic)
+ model parameters.
-```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
-```
+- OPTIONAL files "`[_space-][_desc-]_parameter-_.json`"
+ may be defined to provide only information or parameters relevant to
+ derivation of each relevant [extrinsic](#paramdef-extrinsic) model
+ parameter image.
-Contents of JSON file:
+### Data representations
-```JSON
-{
- "Parameters": {
- "FitMethod": "WLS"
- }
-}
-```
+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.
-A multi-shell, multi-tissue Constrained Spherical Deconvolution fit:
+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)).
-```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
-```
+1. *Scalars* :
-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"
- }
-}
-```
+ 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.
-A NODDI fit:
+1. *Directionally-Encoded Colours (DEC)* :
-```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
-```
+ 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.
-## Model-derived maps (output parameters)
+1. *Spherical coordinates* :
-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.
+ 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.
-```Text
-/
- sub-/
- dwi/
- [_space-]_model-[_desc-]_.nii[.gz]
-```
+ This may take one of two forms:
-### Scalar maps
-
-These maps are saved 3D NIfTI files (x,y,z). Some examples of such maps are as follows:
-
-| `` 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) | microns2 /ms 1 |
-| AD | Axial Diffusivity (also called parallel diffusivity) | DTI, DKI, WMTI (D, Dh, Dr) | microns2 /ms 1 |
-| RD | Radial Diffusivity (also called perpendicular diffusivity) | DTI, DKI, WMTI (D, Dh, Dr) | microns2 /ms 1 |
-| MODE | Mode of the tensor | DTI, DKI, WMTI (D, Dh, Dr) | |
-| LINEARITY | Tensor linearity (Westin 1997) | DTI, DKI, WMTI (D, Dh, Dr) | |
-| PLANARITY | Tensor planarity (Westin 1997) | DTI, DKI, WMTI (D, Dh, Dr) | |
-| SPHERICITY | Tensor sphericity (Westin 1997) | DTI, DKI, WMTI (D, Dh, Dr) | |
-| MK | Mean kurtosis | DKI, WMTI | Unitless |
-| RK | Radial kurtosis | DKI, WMTI | Unitless |
-| AK | Axial kurtosis | DKI, WMTI | Unitless |
-| GFA | Generalized Fractional Anisotropy | CSA, CSD, SHORE, MAPMRI, Forecast (or any model that can be represented as an ODF) | Proportion \[0-1\] |
-| FSUM | Sum of partial volume fractions of stick components | Ball-and-stick(s) | Volume fraction \[0-1\] |
-| Fi | Volume fraction of stick i | Ball-and-stick(s) | Volume fraction \[0-1\] |
-| D | Diffusivity | Ball-and-stick(s) | microns2 /ms 1 |
-| DSTD | Standard deviation of diffusivity | Ball-and-stick(s) | microns2 /ms |
-| RTPP | Return to the plane probability | MAPMRI | Probability \[0-1\] |
-| RTAP | Return to axis probability | MAPMRI | Probability \[0-1\] |
-
-1 For example, for free water in body temperature, the diffusivity in units of microns2 /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:
+ 1. Value per direction
-```Text
-/
- sub-/
- dwi/
- _model-DTI_desc-DEC_FA.nii[.gz]
-```
+ 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. 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.
+
+ 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.
+
+ 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 model 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.
+
+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 harmonics basis.
+
+ Number of image volumes depends on the spherical harmonic basis employed,
+ and the maximal spherical harmonic degree *lmax * (see
+ [spherical harmonics bases](#spherical-harmonics-bases)).
+
+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 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. *Probability Distribution Functions (PDFs)* :
+
+ ***TODO***
+
+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](#paramdef-intrinsic) model parameters section.
+
+### 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](#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;`" 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: *Dxx *, *Dxy *, *Dxz *, *Dyy *, *Dyz *, *Dzz *, *Wxxxx *, *Wyyyy *, *Wzzzz *, *Wxxxy *, *Wxxxz *, *Wxyyy *, *Wyyyz *, *Wxzzz *, *Wyzzz *, *Wxxyy *, *Wxxzz *, *Wyyzz *, *Wxxyz *, *Wxyyz *, *Wxyzz * (*D* is the diffusion tensor, *W* is the kurtosis tensor)xx *, *Dxy *, *Dxz *, *Dyy *, *Dyz *, *Dzz *xx *, *Dcxy *, *Dcxz *, *Dcyy *, *Dcyz *, *Dczz * (*Dc* is the free-water-corrected diffusion tensor);xx *, *Dxy *, *Dxz *, *Dyy *, *Dyz *, *Dzz *, *Wxxxx *, *Wyyyy *, *Wzzzz *, *Wxxxy *, *Wxxxz *, *Wxyyy *, *Wyyyz *, *Wxzzz *, *Wyzzz *, *Wxxyy *, *Wxxzz *, *Wyyzz *, *Wxxyz *, *Wxyyz *, *Wxyzz *, *Dhxx *, *Dhxy *, *Dhxz *, *Dhyy *, *Dhyz *, *Dhzz *, *Drxx *, *Drxy *, *Drxz *, *Dryy *, *Dryz *, *Drzz * (*D* is the diffusion tensor and *W* is the kurtosis tensor);max *; 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
+
+### Extrinsic model parameters
+
+| `` 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 m2 .ms-1 [1](#diffusivity) |
+| `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 m2 .ms-1 [1](#diffusivity) |
+| `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 m2 .ms-1 [1](#diffusivity) |
+| `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 m2 .ms-1 [1](#diffusivity) |
+| `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](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.
+
+### 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 *lmax *
+ and number of image volumes *N*:
+
+ *N* = ((*lmax *+1) x (*lmax *+2)) / 2
+
+ | ***lmax *** | 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 + (*lmax * / 2)
+
+ | ***lmax *** | 0 | 2 | 4 | 6 | 8 | ... |
+ | --------------------- | --: | --: | --: | --: | --: | :--: |
+ | ***N*** | 1 | 2 | 3 | 4 | 5 | etc. |
+
+- `Descoteaux`
+
+ ***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
+ }
+ }
+ ```
+
+-----
+
+1 2 .ms-1
+should be approximately 3.0.
+
+-----
+
+\[Aganj2010\] : Aganj et al. 2010
+
+\[Basser1994\] : Basser et al. 1994
+
+\[Basser1996\] : Basser et al. 1996
+
+\[Behrens2003\] Behrens et al. 2003
+
+\[Behrens2007\] Behrens et al. 2007
+
+\[Calamante2015\] : Calamante et al. 2015
+
+\[Daducci2015\] : Daducci et al. 2015
+
+\[Descoteaux2009\] : Descoteaux et al. 2009
+
+\[Fieremans2011\] : Fieremans et al. 2011
+
+\[Hess2006\] : Hess et al. 2006
+
+\[Hoy2014\] : Hoy et al. 2014
+
+\[Jbabdi2012\] Jbabdi et al. 2012
+
+\[Jensen2005\] : Jensen et al. 2005
+
+\[Jeurissen2014\] : Jeurissen et al. 2014
+
+\[Ozarslan2008\] : Ozarslan et al. 2008
+
+\[Ozarslan2013\] : Ozarslan 2013
+
+\[Paquette2017\] : Paquette et al 2017
+
+\[Pajevic1999\] : Pajevic et al 1999
+
+\[Tournier2007\] : Tournier et al. 2007
+
+\[Tuch2004\] : Tuch 2004
+
+\[Wedeen2008\] : Wedeen et al. 2008
+
+\[Westin1997\] : Westin 1997
+
+\[Zhang2012\] : 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:
-
-| `` 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 |
+\[Zuchelli2017\] : Zuchelli et al. 2017