Skip to content

Commit 518e7a8

Browse files
tsalotsalo
committed
Add metadata fields to schema.
I didn't use any references so the glossary links will be broken.
1 parent 1c7d207 commit 518e7a8

File tree

2 files changed

+307
-146
lines changed

2 files changed

+307
-146
lines changed

‎src/derivatives/diffusion-derivatives.md‎

Lines changed: 59 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -245,94 +245,11 @@ REQUIRED field `"Model"` defines a dictionary that contains relevant information
245245
about what the model is and how it was fit to empirical image data.
246246
The following table defines reserved fields within the `"Model"` sub-dictionary.
247247

248-
{{ MACROS___make_metadata_table(
249-
{ "bootstrap": {
250-
"LongName": "BootstrapParameters",
251-
"Description": (
252-
"OPTIONAL",
253-
"Dictionary. Parameters relating to the generation of multiple realizations of the model fit using bootstrapping.",
254-
)
255-
},
256-
"description": {
257-
"LongName": "Description",
258-
"Description":(
259-
"OPTIONAL",
260-
"String. Extended text-based information to describe the model.",
261-
)
262-
},
263-
"parameters": {
264-
"LongName": "Parameters",
265-
"Description":(
266-
"OPTIONAL",
267-
"Dictionary. Parameters that influenced the process of fitting the model to empirical image data (see examples below).",
268-
)
269-
},
270-
"url": {
271-
"LongName": "URL",
272-
"Description": (
273-
"OPTIONAL",
274-
"String. URL to the specific implementation of the model utilized.",
275-
)
276-
}
277-
}
278-
) }}
248+
{{ MACROS___make_subobject_table("metadata.Model") }}
279249

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

282-
{{ MACROS___make_metadata_table(
283-
{ "fit_method": {
284-
"LongName": "FitMethod",
285-
"Description": (
286-
"OPTIONAL",
287-
"String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal.",
288-
),
289-
"Levels":
290-
{"ols": "Ordinary Least Squares",
291-
"wls": "Weighted Least Squares",
292-
"iwls": "Iterative Weighted Least Squares",
293-
"nlls": "Non-Linear Least Squares"
294-
}
295-
},
296-
"iterations": {
297-
"LongName": "Iterations",
298-
"Description": (
299-
"OPTIONAL",
300-
"Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter.",
301-
)
302-
},
303-
"outlier_rejection_method": {
304-
"LongName": "OutlierRejectionMethod",
305-
"Description": ("OPTIONAL",
306-
"String. Text describing any form of rejection of outlier values that was performed during fitting of the model.",
307-
)
308-
},
309-
"samples": {
310-
"LongName": "Samples",
311-
"Description":
312-
(
313-
"OPTIONAL",
314-
"Integer. The number of realizations of a diffusion model from which statistical summaries (such as mean, standard deviation) of those parameters were computed.",
315-
)
316-
},
317-
"diso": {
318-
"LongName": "IsotropicDiffusivity",
319-
"Description":
320-
(
321-
"OPTIONAL",
322-
"Float. Diffusivity of an isotropic component (in units of mm^2/s)",
323-
)
324-
},
325-
"dpar": {
326-
"LongName": "ParallelDiffusivity",
327-
"Description":
328-
(
329-
"OPTIONAL",
330-
"Float. Diffusivity of a axial/parallel component (in units of mm^2/s)",
331-
)
332-
}
333-
334-
}
335-
) }}
252+
{{ MACROS___make_subobject_table("metadata.Model.properties.Parameters") }}
336253

337254

338255
#### Parameter metadata
@@ -347,6 +264,16 @@ Some fields are relevant only to specific [orientation encoding types](#orientat
347264
- Where a field is *not* relevant for the corresponding image,
348265
that metadata field MUST NOT be specified.
349266

267+
{{ MACROS___make_metadata_table(
268+
{
269+
"BootstrapAxis": ("OPTIONAL", "Applicable to any orientation encoding type"),
270+
"Description": ("OPTIONAL", "Applicable to any orientation encoding type"),
271+
"NonNegativity": ("OPTIONAL", "Applicable to all orientation encoding types except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector)"),
272+
"OrientationEncoding": ("REQUIRED", "Applicable to any orientation encoding type"),
273+
"ParameterURL": ("OPTIONAL", "Applicable to any orientation encoding type"),
274+
"ResponseFunction": ("OPTIONAL", "Applicable to [spherical harmonics](#encoding-sh)"),
275+
}
276+
) }}
350277

351278
| **Key name** | Relevant [orientation encoding types](#orientation-encoding-types) | **Description** |
352279
| ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -359,6 +286,8 @@ Some fields are relevant only to specific [orientation encoding types](#orientat
359286

360287
Dictionary `"OrientationEncoding"` has the following reserved keywords:
361288

289+
{{ MACROS___make_subobject_table("metadata.OrientationEncoding") }}
290+
362291
| **Key name** | Relevant [orientation encoding types](#orientation-encoding-types) | **Description** |
363292
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364293
| 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. |
@@ -373,54 +302,20 @@ Dictionary `"OrientationEncoding"` has the following reserved keywords:
373302

374303
Field `"OrientationEncoding"["Reference"]` MUST contain one of the following values:
375304

376-
{{ MACROS___make_metadata_table(
377-
{
378-
"bvec": {
379-
"LongName": "bvec",
380-
"Description": (
381-
"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.",
382-
)
383-
},
384-
"ijk": {
385-
"LongName": "ijk",
386-
"Description": (
387-
"The three spatial image axes define the orientation.",
388-
)
389-
},
390-
"xyz": {
391-
"LongName": "ijk",
392-
"Description": (
393-
"The 'real' / 'scanner' space axes, which are independent of the NIfTI image header transform, define the orientation reference.",
394-
)
395-
}
396-
}
397-
) }}
305+
| **Key name** | **LongName** | **Description** |
306+
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
307+
| 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. |
308+
| ijk | ijk | The three spatial image axes define the orientation. |
309+
| xyz | xyz | The 'real' / 'scanner' space axes, which are independent of the NIfTI image header transform, define the orientation reference. |
398310

399311
Dictionary `"ResponseFunction"` has the following reserved keywords:
400312

401-
{{ MACROS___make_metadata_table(
402-
{
403-
"coefficients": {
404-
"LongName": "Coefficients",
405-
"Description": (
406-
"REQUIRED",
407-
"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.",
408-
)
409-
},
410-
"type": {
411-
"LongName": "Type",
412-
"Description": (
413-
"REQUIRED",
414-
"String. The mathematical form in which the response function coefficients are provided; see further below. ",
415-
),
416-
"Levels": {
417-
"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.",
418-
"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."
419-
}
420-
}
421-
},
422-
) }}
313+
{{ MACROS___make_subobject_table("metadata.ResponseFunction") }}
423314

315+
| **Key name** | **LongName** | **Description** |
316+
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
317+
| 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. |
318+
| 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.) |
424319

425320

426321
### Demonstrative examples
@@ -449,7 +344,9 @@ A guide for using macros can be found at
449344
) }}
450345

451346
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))
347+
452348
Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
349+
453350
Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
454351

455352
Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
@@ -549,7 +446,9 @@ A guide for using macros can be found at
549446
) }}
550447

551448
Dimensions of NIfTI image "`sub-01_model-csd_param-wm_dwimap.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
449+
552450
Dimensions of NIfTI image "`sub-01_model-csd_param-gm_dwimap.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
451+
553452
Dimensions of NIfTI image "`sub-01_model-csd_param-csf_dwimap.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
554453

555454
Contents of JSON file "`sub-01_model-csd_param-wm_dwimap.json`":
@@ -625,10 +524,12 @@ Contents of JSON file "`sub-01_model-csd_param-csf_dwimap.json`":
625524
"Type": "sh"
626525
},
627526
"ResponseFunction": {
628-
"Coefficients": [ [ 3544.90770181 ],
629-
[ 134.441453035 ],
630-
[ 32.0826839826 ],
631-
[ 29.3674604452 ] ],
527+
"Coefficients": [
528+
[ 3544.90770181 ],
529+
[ 134.441453035 ],
530+
[ 32.0826839826 ],
531+
[ 29.3674604452 ]
532+
],
632533
"Type": "zsh"
633534
}
634535
}
@@ -656,28 +557,29 @@ Notes:
656557

657558
#### A Neurite Orientation and Dispersion Imaging (NODDI) fit
658559

659-
A fit of the model using the AMICO
660-
software.
560+
A fit of the model using the AMICO software.
661561

662562
{{ MACROS___make_filetree_example(
663563
{
664-
"noddi_pipeline": {
665-
"sub-01": {
666-
"dwi": {
667-
"sub-01_model-noddi_param-direction_dwimap.nii.gz": "",
668-
"sub-01_model-noddi_param-direction_dwimap.json": "",
669-
"sub-01_model-noddi_param-odi_dwimap.nii.gz": "",
670-
"sub-01_model-noddi_param-odi_dwimap.json": "",
671-
"sub-01_model-noddi_param-icvf_dwimap.nii.gz": "",
672-
"sub-01_model-noddi_param-icvf_dwimap.json": "",
673-
},
564+
"noddi_pipeline": {
565+
"sub-01": {
566+
"dwi": {
567+
"sub-01_model-noddi_param-direction_dwimap.nii.gz": "",
568+
"sub-01_model-noddi_param-direction_dwimap.json": "",
569+
"sub-01_model-noddi_param-odi_dwimap.nii.gz": "",
570+
"sub-01_model-noddi_param-odi_dwimap.json": "",
571+
"sub-01_model-noddi_param-icvf_dwimap.nii.gz": "",
572+
"sub-01_model-noddi_param-icvf_dwimap.json": "",
573+
},
574+
},
674575
},
675-
},
676576
}
677577
) }}
678578

679579
Dimensions of NIfTI image "`sub-01_model-noddi_param-direction_dwimap.nii.gz`": *I*x*J*x*K*3 ([unit vector](#encoding-3vector))
580+
680581
Dimensions of NIfTI image "`sub-01_model-noddi_param-odi_dwimap.nii.gz`": *I*x*J*x*K*1 ([scalar](#encoding-scalar))
582+
681583
Dimensions of NIfTI image "`sub-01_model-noddi_param-icvf_dwimap.nii.gz`": *I*x*J*x*K*1 ([scalar](#encoding-scalar))
682584

683585

@@ -776,13 +678,21 @@ A guide for using macros can be found at
776678
) }}
777679

778680
Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
681+
779682
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)
683+
780684
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)
685+
781686
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)
687+
782688
Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
689+
783690
Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
691+
784692
Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
693+
785694
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 realizations)
695+
786696
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 realizations)
787697

788698
Contents of JSON file "`sub-01_model-bs_desc-mean_param-s0_dwimap.json`":
@@ -945,6 +855,7 @@ Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
945855
},
946856
"Units": "TODO"
947857
}
858+
```
948859

949860
Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
950861

@@ -971,6 +882,7 @@ Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
971882
"Type": "unitspherical"
972883
}
973884
}
885+
```
974886

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

@@ -995,6 +907,7 @@ Contents of JSON file "`sub-01_model-bs_desc-merged_param-vf_dwimap.json`":
995907
"Type": "scalar"
996908
}
997909
}
910+
```
998911

999912
Notes:
1000913

0 commit comments

Comments
 (0)