Diffusion derivatives

Preprocessed diffusion-weighted images

• As with raw diffusion imaging data, inclusion of gradient orientation information is REQUIRED. While 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, 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 for derivative data, a JSON sidecar file is REQUIRED due to the REQUIRED SkullStripped field.

Template:

sub-<label>/
    [ses-<label>/]
        dwi/
            <source-entities>[_space-<label>][_desc-<label>][_res-<label>]_dwi.json
            <source-entities>[_space-<label>][_desc-<label>][_res-<label>]_dwi.nii[.gz]
            <source-entities>[_space-<label>]_model-<label>_param-<label>[_desc-<label>][_res-<label>]_dwimap.json
            <source-entities>[_space-<label>]_model-<label>_param-<label>[_desc-<label>][_res-<label>]_dwimap.nii[.gz]

Legend:

• For more information about filename elements (for example, entities, suffixes, extensions), follow the links embedded in the filename template.

• <matches> is a placeholder to denote an arbitrary (and valid) sequence of entities and labels at the beginning of the filename (only BIDS "raw").

• <source-entities> is a placeholder to denote an arbitrary sequence of entities and labels at the beginning of the filename matching a source file from which the file derives (only BIDS-Derivatives).

• Filename entities or directories between square brackets (for example, [_ses-<label>]) are OPTIONAL.

• Some entities may only allow specific values, in which case those values are listed in <>, separated by |.

• _<suffix> means that there are several (>6) valid suffixes for this filename pattern.

• .<extension> means that there are several (>6) valid extensions for this file type.

• [.gz] means that both the unzipped and gzipped versions of the extension are valid.

Manual:

<pipeline_name>/
    sub-<label>/
        [ses-<label>/]
            dwi/
                <source-entities>[_space-<space>]_desc-preproc_dwi.nii[.gz]
                <source-entities>[_space-<space>]_desc-preproc_dwi.bval
                <source-entities>[_space-<space>]_desc-preproc_dwi.bvec
                <source-entities>[_space-<space>]_desc-preproc_dwi.json

Diffusion models

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

<pipeline_name>/
    sub-<label>/
        [ses-<label>/]
            dwi/
                <source-entities>[_space-<space>]_model-<label>_param-<label1>[_desc-<label>]_dwimap.nii[.gz]
                <source-entities>[_space-<space>]_model-<label>_param-<label1>[_desc-<label>]_dwimap.json
                <source-entities>[_space-<space>]_model-<label>_param-<label2>[_desc-<label>]_dwimap.nii[.gz]
                <source-entities>[_space-<space>]_model-<label>_param-<label2>[_desc-<label>]_dwimap.json
                <source-entities>[_space-<space>]_model-<label>_param-<label3>[_desc-<label>]_dwimap.nii[.gz]
                <source-entities>[_space-<space>]_model-<label>_param-<label3>[_desc-<label>]_dwimap.json

• Files "<source-entities>_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-entities>_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.

Orientation encoding types

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 enumerated below, accompanied by requisite information specific to each representation.

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.

1. Scalar image:

   Image data that do not encode orientation information are referred to henceforth here as "scalar" parameters.

2. Directionally-Encoded Colors (DEC):

   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.

3. Spherical coordinates:

   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 3-tuple spherical coordinate, using ISO convention for both the order of parameters and reference frame for angles:

      1. Distance from origin, encoding some non-negative parameter of interest.

      2. Inclination / polar angle in radians, relative to the zenith direction being the positive direction of the third reference axis (see parameter metadata);

      3. Azimuth angle, in radians, orthogonal to the zenith direction, with value of 0.0 corresponding to the first reference axis (see parameter metadata), increasing toward the positive direction of the second reference axis.

      Number of image volumes is equal to (3xN), where N is the maximum number of discrete orientations in any voxel in the image.

   2. Orientations only

      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 (2xN), where N is the maximum number of discrete orientations in any voxel in the image.

4. 3-Vectors:

   An image where data across volumes within each voxel encode one or more discrete orientations using triplets of axis dot products.

   This may take one of two forms:

   1. Value per orientation

      The norm of the 3-vector encodes some non-negative parameter of interest, while its normalized form encodes an orientation on the unit sphere.

   2. Orientations only

      Each triplet of values encodes an orientation on the unit sphere (that is, the vector norm MUST be 1.0); no quantitative value is associated with each orientation.

   Number of image volumes is equal to (3xN), where N is the maximum number of discrete orientations in any voxel in the image.

5. Tensor:

   An image where volumes encode coefficients of a tensor.

   • For Rank 2 tensors:

     If antipodal symmetry is set (or implicitly assumed), then the image MUST contain six volumes, in the order: D₁₁, D₁₂, D₁₃, D₂₂, D₂₃, D₃₃, where 1, 2 and 3 index the three spatial dimensions according to their reference (see field "OrientationEncoding"["Reference"] in parameter metadata). If the data are not antipodally symmetric, then the image MUST contain nine volumes, in the order: D₁₁, D₁₂, D₁₃, D₂₁, D₂₂, D₂₃, D₃₁, D₃₂, *D₃₃, with subscripts indexing row then column.

6. Spherical Harmonics (SH):

   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_max (see spherical harmonics bases).

7. Amplitudes:

   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 orientations on the unit sphere along which samples for the spherical function in each voxel are provided; these orientations MUST themselves be provided in the associated sidecar JSON file (see 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 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, along which those multiple realizations are stored.

For some models, it is common to explicitly store both the multiple realizations of the model and either the parameters corresponding to the maximum a posteriori fit or the mean of each parameter computed across those realizations. 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.

2. 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	Requirement Level	Data type	Description
Description	OPTIONAL	string	Free-form natural language description.
TermURL	OPTIONAL	string	URL pointing to a formal definition of this type of data in an ontology available on the web. For example: https://www.ncbi.nlm.nih.gov/mesh/68008297 for "male".
BootstrapParameters	OPTIONAL	object	Parameters relating to the generation of multiple realizations of the model fit using bootstrapping.
Parameters	OPTIONAL	object	Dictionary containing information about the parameters of the model.

Dictionary "Model["Parameters"]" has the following reserved keywords that may be applicable to a broad range of models:

Key name	Requirement Level	Data type	Description
FitMethod	OPTIONAL	string	The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Must be one of: "ols", "wls", "iwls", "nlls".
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. Must be a number greater than or equal to 0.
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 realizations of a diffusion model from which statistical summaries (such as mean, standard deviation) of those parameters were computed. Must be a number greater than or equal to 0.
IsotropicDiffusivity	OPTIONAL	number	Diffusivity of an isotropic component (in units of mm^2/s).
ParallelDiffusivity	OPTIONAL	number	Diffusivity of a axial/parallel component (in units of mm^2/s).

Parameter metadata

The following tables define reserved fields relevant to individual model parameters.

Some fields are relevant only to specific 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.

Auto-generated table:

Key name	Requirement Level	Data type	Description
BootstrapAxis	OPTIONAL	integer	If multiple realizations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realizations are stored. Applicable to any orientation encoding type. Must be a number greater than or equal to 0.
Description	OPTIONAL	string	Free-form natural language description. Applicable to any orientation encoding type.
NonNegativity	OPTIONAL	string	Specifies whether, during model fitting, the parameter was regularized to not take extreme negative values, or was explicitly forbidden from taking negative values. Applicable to all orientation encoding types except spherical coordinates and 3-vectors. Must be one of: "regularized", "constrained".
OrientationEncoding	REQUIRED	object	Dictionary containing information about the orientation encoding of the model. Applicable to any orientation encoding type.
ParameterURL	OPTIONAL	string	URL to documentation that describes the specific model parameter that is encoded within the data file. Applicable to any orientation encoding type.
ResponseFunction	OPTIONAL	object	Dictionary containing information about the response function used to fit the model. Applicable to spherical harmonics.

Manual table:

Key name	Relevant orientation encoding types	Description
BootstrapAxis	Any	OPTIONAL. Integer. If multiple realizations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realizations are stored.
Description	Any	OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.
NonNegativity	All except spherical coordinates and 3-vectors	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.
ParameterURL	Any	OPTIONAL. String. URL to documentation that describes the specific model parameter that is encoded within the data file.
ResponseFunction	Spherical harmonics	OPTIONAL. Dictionary. Specifies a response function that was utilized by a deconvolution algorithm; more details below.

Dictionary "OrientationEncoding" has the following reserved keywords:

Key name	Requirement Level	Data type	Description
AmplitudesDirections	OPTIONAL	array of arrays	List of lists of floats. 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. The length of the list must be equal to the number of volumes in the image. REQUIRED for "Type": "amplitudes"; MUST NOT be specified otherwise.
AntipodalSymmetry	OPTIONAL	boolean	Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted. Must be one of: "true", "false".
EncodingAxis	REQUIRED	integer	Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding. Must be a number greater than or equal to 0.
FillValue	OPTIONAL	number	Float. Value stored in image when the number of discrete orientations in a given voxel is fewer than the maximal number for that image.
Reference	REQUIRED	string	The reference coordinate system for the orientation encoding. Must be one of: "bvec", "ijk", "xyz".
SphericalHarmonicsBasis	OPTIONAL	string	String. Options are: { mrtrix3, descoteaux }. Details are provided in the spherical harmonics bases section. Must be one of: "mrtrix3", "descoteaux".
SphericalHarmonicsDegree	OPTIONAL	integer	Integer. The maximal spherical harmonic order lmax; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in the spherical harmonics bases section. Must be a number greater than or equal to 0.
TensorRank	OPTIONAL	integer	Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2. REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Must be a number greater than or equal to 0.
Type	REQUIRED	string	Specifies the type of orientation information (if any) encoded in the NIfTI image. Must be one of: "scalar", "dec", "unitspherical", "spherical", "unit3vector", "3vector", "tensor", "sh", "amplitudes".

The following fields should only be present when OrientationEncoding.Type is "amplitudes":

Key name	Requirement Level	Data type	Description
AmplitudesDirections	REQUIRED if OrientationEncoding.Type is "amplitudes"	array of arrays	List of lists of floats. 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. The length of the list must be equal to the number of volumes in the image. REQUIRED for "Type": "amplitudes"; MUST NOT be specified otherwise.

The following fields should only be present when OrientationEncoding.Type is "sh":

Key name	Requirement Level	Data type	Description
SphericalHarmonicsBasis	REQUIRED if OrientationEncoding.Type is "sh"	string	String. Options are: { mrtrix3, descoteaux }. Details are provided in the spherical harmonics bases section. Must be one of: "mrtrix3", "descoteaux".
SphericalHarmonicsDegree	OPTIONAL if OrientationEncoding.Type is "sh"	integer	Integer. The maximal spherical harmonic order lmax; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in the spherical harmonics bases section. Must be a number greater than or equal to 0.

The following fields should only be present when OrientationEncoding.Type is "tensor":

Key name	Requirement Level	Data type	Description
TensorRank	REQUIRED if OrientationEncoding.Type is "tensor"	integer	Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2. REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Must be a number greater than or equal to 0.

The following fields should only be present when OrientationEncoding.Type is not "scalar":

Key name	Requirement Level	Data type	Description
EncodingAxis	REQUIRED if OrientationEncoding.Type is not "scalar"	integer	Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding. Must be a number greater than or equal to 0.
Reference	REQUIRED if OrientationEncoding.Type is not "scalar"	string	The reference coordinate system for the orientation encoding. Must be one of: "bvec", "ijk", "xyz".

Manual table:

Key name	Relevant orientation encoding types	Description
AmplitudesDirections	Amplitudes	REQUIRED for "Type": "amplitudes"; MUST NOT be specified otherwise. List of lists of floats. 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. The length of the list must be equal to the number of volumes in the image.
AntipodalSymmetry	spherical coordinates, 3-vectors, tensor, amplitudes, spherical harmonics	OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.
EncodingAxis	All except scalar	REQUIRED. Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding.
FillValue	Scalar, spherical coordinates, 3-vectors	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	REQUIRED. String; allowed values: { bvec, ijk, xyz }. Defines the reference coordinate system against which orientation information is encoded (more below).
SphericalHarmonicBasis	Spherical harmonics	REQUIRED for "Type": "sh"; MUST NOT be specified otherwise. String. Options are: { mrtrix3, descoteaux }. Details are provided in the spherical harmonics bases section.
SphericalHarmonicDegree	Spherical harmonics	OPTIONAL for "Type": "sh"; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order lmax; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in spherical harmonics bases section.
TensorRank	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:

Key name	LongName	Description
bvec	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	ijk	The three spatial image axes define the orientation.
xyz	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:

Auto-generated table:

Key name	Requirement Level	Data type	Description
Coefficients	REQUIRED	array	The coefficients of the response function. 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	The mathematical form in which the response function coefficients are provided; see further below. Levels are "eigen" (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.) and "zsh" (Either of (1) a list of floating-point values: Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero; OR (2) 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 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.) Must be one of: "eigen", "zsh".

Manual table:

Key name	LongName	Description
coefficients	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	type	REQUIRED. String. The mathematical form in which the response function coefficients are provided; see further below. Levels are "eigen" (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.) and "zsh" (Either of (1) a list of floating-point values: Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero; OR (2) 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 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

A basic Diffusion Tensor fit

└─ 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": IxJxKx6 (symmetric rank 2 tensor image)

Dimensions of NIfTI image "sub-01_model-tensor_param-s0_dwimap.nii.gz": IxJxK (scalar)

Dimensions of NIfTI image "sub-01_model-tensor_param-fa_dwimap.nii.gz": IxJxK (scalar)

Contents of file sub-01_model-tensor_param-diffusivity_dwimap.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:

{
    "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:

{
    "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

└─ 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 

Dimensions of NIfTI image "sub-01_model-csd_param-wm_dwimap.nii.gz": IxJxKx45 (spherical harmonics)

Dimensions of NIfTI image "sub-01_model-csd_param-gm_dwimap.nii.gz": IxJxKx1 (spherical harmonics)

Dimensions of NIfTI image "sub-01_model-csd_param-csf_dwimap.nii.gz": IxJxKx1 (spherical harmonics)

Contents of JSON file "sub-01_model-csd_param-wm_dwimap.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-gm_dwimap.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-csf_dwimap.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:

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

A Neurite Orientation and Dispersion Imaging (NODDI) fit

A fit of the model using the AMICO software.

└─ noddi_pipeline/
   └─ sub-01/
      └─ dwi/
         ├─ sub-01_model-noddi_param-direction_dwimap.nii.gz 
         ├─ sub-01_model-noddi_param-direction_dwimap.json 
         ├─ sub-01_model-noddi_param-odi_dwimap.nii.gz 
         ├─ sub-01_model-noddi_param-odi_dwimap.json 
         ├─ sub-01_model-noddi_param-icvf_dwimap.nii.gz 
         └─ sub-01_model-noddi_param-icvf_dwimap.json 

Dimensions of NIfTI image "sub-01_model-noddi_param-direction_dwimap.nii.gz": IxJxK3 (unit vector)

Dimensions of NIfTI image "sub-01_model-noddi_param-odi_dwimap.nii.gz": IxJxK1 (scalar)

Dimensions of NIfTI image "sub-01_model-noddi_param-icvf_dwimap.nii.gz": IxJxK1 (scalar)

Contents of JSON file "sub-01_model-noddi_param-direction_dwimap.json":

{
    "Model": {
        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
        "Parameters": {
            "ParallelDiffusivity": 0.0017,
            "IsotropicDiffusivity": 0.003
            },
    },
    "Description": "Direction",
    "OrientationEncoding": {
        "EncodingAxis": 3,
        "Type": "unit3vector",
        "Reference": "xyz",
    },
}

Contents of JSON file "sub-01_model-noddi_param-odi_dwimap.json":

{
    "Model": {
        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
        "Parameters": {
            "ParallelDiffusivity": 0.0017,
            "IsotropicDiffusivity": 0.003
            },
    },
    "Description": "Orientation dispersion index",
    "ParameterURL": "https://doi.org/10.1016/j.neuroimage.2012.03.072"
}

Contents of JSON file "sub-01_model-noddi_param-icvf_dwimap.json":

{
    "Model": {
        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
        "Parameters": {
            "ParallelDiffusivity": 0.0017,
            "IsotropicDiffusivity": 0.003
            },
        },
    "Description": "Intra-cellular volume fraction CVF",
    "ParameterURL": "https://doi.org/10.1016/j.neuroimage.2012.03.072"
}

An FSL bedpostx Ball-And-Sticks fit

This example includes both bootstrap realizations of the model fit, and the aggregated means of those parameters across realizations.

└─ 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": IxJxK (scalar)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz": IxJxKx(2xN) (spherical coordinates, orientations only; N orientations per voxel)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz": IxJxKx(3xN) (3-vectors, unit norm; N orientations per voxel)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz": IxJxKxN (scalar; N values per voxel)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz": IxJxK (scalar)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz": IxJxK (scalar)

Dimensions of NIfTI image "sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz": IxJxK (scalar)

Dimensions of NIfTI image "sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz": IxJxKx(2xN)xR (spherical coordinates, orientations only; N orientations per voxel; R bootstrap realizations)

Dimensions of NIfTI image "sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz": IxJxKxNxR (scalar; N values per voxel; R bootstrap realizations)

Contents of JSON file "sub-01_model-bs_desc-mean_param-s0_dwimap.json":

{
    "Description": "Estimated signal intensity with no diffusion weighting, ie. S0; mean across bootstrap realizations",
    "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":

{
    "Description": "Fibre orientations encoded using polar angles; mean across bootstrap realizations",
    "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": "bvec",
        "Type": "unitspherical"
    }
}

Contents of JSON file "sub-01_model-bs_desc-mean_param-vector_dwimap.json":

{
    "Description": "Fibre orientations encoded using 3-vectors; mean across bootstrap realizations",
    "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": "bvec",
        "Type": "unit3vector"
    }
}

Contents of JSON file "sub-01_model-bs_desc-mean_param-vf_dwimap.json":

{
    "Description": "Volume fractions of stick components; mean across bootstrap realizations",
    "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"
    }
}

Contents of JSON file "sub-01_model-bs_desc-mean_param-vfsum_dwimap.json":

{
    "Description": "Sum of volume fractions of stick components; mean across bootstrap realizations",
    "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":

{
    "Description": "Diffusivity; mean across bootstrap realizations",
    "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":

{
    "Description": "Diffusivity variance parameter; mean across bootstrap realizations",
    "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":

{
    "BootstrapAxis": 4,
    "Description": "Fibre orientations encoded using polar angles; concatenated bootstrap realizations",
    "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": "bvec",
        "Type": "unitspherical"
    }
}

Contents of JSON file "sub-01_model-bs_desc-merged_param-vf_dwimap.json":

{
    "BootstrapAxis": 4,
    "Description": "Volume fractions of stick components; concatenated bootstrap realizations",
    "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 utilized to distinguish between the comprehensive set of all bootstrap realizations and the computed mean statistics of parameters across all realizations 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 "*_param-vf_desc-mean*_*", 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 realizations 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".

Appendix

Spherical Harmonics

• Concepts shared across all spherical harmonics bases:

  • Basis functions:

    

    for integer order l, phase m, associated Legendre polynomials P.

  • (Truncated) basis coefficients:

    

    for maximum spherical harmonic order l_max.

  • Functions assumed to be real: conjugate symmetry is assumed, that is, Y(l,-m) = Y(l,m)*, where * denotes the complex conjugate.

  • Antipodally symmetric: all basis functions with odd degree are assumed zero; AntipodalSymmetry MUST NOT be set to False.

  • Utilized basis functions:

    • mrtrix3

    

    • descoteaux

    

  • Mapping between image volume V and spherical harmonic basis function coefficient Y_l,m:

    V_l,m = (l(l+1) / 2) + m

    V	Coefficient
    0	Y0,0
    1	Y2,-2
    2	Y2,-1
    3	Y2,0
    4	Y2,1
    5	Y2,2
    6	Y4,-4
    7	Y4,-3
    ...	...

  • Relationship between maximal spherical harmonic degree l_max and number of image volumes N:

    N = ((l_max+1) x (l_max+2)) / 2

    lmax	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 assumed to be zero; used for response function definition and similar) and number of coefficients N:

    N = 1 + (l_max / 2)

    lmax	0	2	4	6	8	10	...
    N	1	2	3	4	5	6	...