Skip to content

Commit b72ce06

Browse files
arokemarokem
committed
Completes the transition from the Google doc.
Also, adds schema objects metadata specifications for sidecar items.
1 parent b128628 commit b72ce06

2 files changed

Lines changed: 159 additions & 19 deletions

File tree

‎src/derivatives/diffusion-derivatives.md‎

Lines changed: 99 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -24,40 +24,41 @@ unequivocally identify the data type from which the tractogram originated.
2424
For example:
2525

2626
```Text
27-
sub–01/
28-
dwi/
29-
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.trx
30-
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.json
31-
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.trx
32-
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.json
27+
pyAFQ/
28+
sub–01/
29+
dwi/
30+
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.trx
31+
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.json
32+
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.trx
33+
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.json
3334
```
3435

35-
The JSON sidecar accompanying the tractogram can contain the following metadata
36+
The JSON sidecar accompanying the tractogram contains the following metadata
3637
fields:
3738

3839
{{ MACROS___make_metadata_table(
3940
{
4041
"Name": ("OPTIONAL", "String", "A human-readable name corresponding to the primary tractography algorithm and/or software used to generate the streamlines data."),
4142
"Description": ("OPTIONAL", "String", "A longer description of the nature of the tractography experiment"),
4243
"URL": ("OPTIONAL", "String", "A web link to a more exhaustive description of the process by which the tractography data were generated. This could be a reference to a journal article, software, software command, documentation, or pipeline description."),
43-
"StreamlineSeeding": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 5a."),
44-
"StreamlinePropagation": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 6a."),
45-
"StreamlineTermination": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 7a."),
46-
"StreamlineAcceptanceCriteria": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 8a."),
47-
"StreamlineReconstructionDensity": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 9a."),
44+
"StreamlineSeeding": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 2a."),
45+
"StreamlinePropagation": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 3a."),
46+
"StreamlineTermination": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 4a."),
47+
"StreamlineAcceptanceCriteria": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 5a."),
48+
"StreamlineReconstructionDensity": ("OPTIONAL", "Dict", "The contents of this dictionary are described in Table 6a."),
4849
}
4950
) }}
5051

51-
Table 5a (contents of the value for key “StreamlineSeeding”)
52+
Table 2a (contents of the value for key `StreamlineSeeding`)
5253

5354
{{ MACROS___make_metadata_table(
5455
{
55-
"Sources": ("REQUIRED", "List", "A list where each item describes a mechanism by which streamline seed points were derived. The contents of the elements of this list are described in Table 5b"),
56-
"AcceptanceCriteria": ("OPTIONAL", "List", "he contents of this list are described in Table 5c"),
56+
"Sources": ("REQUIRED", "List", "A list where each item describes a mechanism by which streamline seed points were derived. The contents of the elements of this list are described in Table 2b"),
57+
"AcceptanceCriteria": ("OPTIONAL", "List", "he contents of this list are described in Table 2c"),
5758
}
5859
) }}
5960

60-
Table 5b (contents of elements within list `StreamlineSeeding[“Sources”]`):
61+
Table 2b (contents of elements within list `StreamlineSeeding["Sources"]`):
6162

6263
{{ MACROS___make_metadata_table(
6364
{
@@ -66,11 +67,11 @@ Table 5b (contents of elements within list `StreamlineSeeding[“Sources”]`):
6667
"SeedsPerElement": ("Either REQUIRED or MUST NOT be specified based on the value of 'Type'", "Int", "For seeding mechanisms that involve a fixed number of streamline seeds for every image element in the seeding source ('RandomPerElement', 'GridPerElement', 'CountPerElement'), this value dictates the number of seeds to be drawn for each such element. For 'GridPerElement', this number must be a perfect cube."),
6768
"AttemptsPerSeed": ("OPTIONAL", "Int", " If specified, it must be a positive integer. For a stochastic tracking algorithm, this is the number of attempts of initiation that are allowed in each seed."),
6869
"Unidirectional": ("OPTIONAL", "Binary", "Specifies whether streamline propagation occurred in one direction from the seed point only, or in two antipodally symmetric directions."),
69-
"InitialDirection": ("OPTIONAL", "Dict", "If absent, assume that the initial streamline tangent from the seed point was determined using the same mechanism as that used for orientation sampling during streamline propagation, but unconstrained by a prior incoming tangent. See Table 5c for possible values."),
70+
"InitialDirection": ("OPTIONAL", "Dict", "If absent, assume that the initial streamline tangent from the seed point was determined using the same mechanism as that used for orientation sampling during streamline propagation, but unconstrained by a prior incoming tangent. See Table 2d for possible values."),
7071
}
7172
) }}
7273

73-
Table 5c (contents of elements of dict `StreamlineSeeding[AcceptanceCriteria]`):
74+
Table 2c (contents of elements of dict `StreamlineSeeding["AcceptanceCriteria"]`):
7475

7576
{{ MACROS___make_metadata_table(
7677
{
@@ -80,7 +81,86 @@ Table 5c (contents of elements of dict `StreamlineSeeding[AcceptanceCriteria]`):
8081
}
8182
) }}
8283

84+
Table 2d (contents of elements of dict `StreamlineSeeding["InitialDirection"]`):
8385

84-
# Tracking methods
86+
TODO
87+
88+
Table 3a (contents of the value for key `StreamlinePropagation`):
89+
90+
{{ MACROS___make_metadata_table(
91+
{
92+
"Algorithm": ("REQUIRED", "Dict", "The contents of this dictionary are described in Table 3b."),
93+
"AnglePerStep": ("OPTIONAL", "Float", "The maximal change in degrees in the streamline tangent between successive steps. Note that exactly how this parameter is interpreted may depend on the value of IntegrationOrder."),
94+
"Interpolation": ("REQUIRED", "String", "Selection from the following: ['Nearest', 'Linear', 'Cubic', 'Spline']. The mechanism by which sub-voxel information is drawn from the Source based on the precise streamline location."),
95+
"InterpolationOrder": ("REQUIRED", "Int", "The order of interpolation used (or 0 if linear)"),
96+
"MinimumRadius": ("OPTIONAL", "Float", "The radius in mm of the circle formed by a streamline consistently turning at the maximum curvature angle at each step."),
97+
"IntegrationOrder": ("OPTIONAL", "Int", "Polynomial complexity of numerical integration of fibre orientations over space to form the streamlines."),
98+
"Source": ("REQUIRED", "String", "Filesystem path or BIDS URI to data used in the determination of streamline tangents during propagation."),
99+
"StepSize": ("OPTIONAL", "Float", "The distance in mm covered by successive steps of the streamline algorithm. Note that this is not necessarily equivalent to the distance in mm between vertices in the tractogram as stored on file."),
100+
"AttemptsPerVertex": ("OPTIONAL", "Int", "The maximal number of probabilistic attempts to make in propagating from a streamline vertex before ceasing propagation."),
101+
}
102+
) }}
103+
104+
Table 3b (contents of dict `StreamlinePropagation["Algorithm"]`):
105+
106+
{{ MACROS___make_metadata_table(
107+
{
108+
"Name": ("REQUIRED", "String", "A human-readable name corresponding to the tractography algorithm used to generate the streamlines."),
109+
"Description": ("OPTIONAL", "String", "A longer description of the nature of the tractography algorithm."),
110+
"URL": ("OPTIONAL", "String", "A web link to a more exhaustive description of the algorithm used to generate the tractography data."),
111+
}
112+
) }}
113+
114+
Table 4a (contents of the value for key `StreamlineTermination`):
115+
116+
{{ MACROS___make_metadata_table(
117+
{
118+
"AnatomicalSegmentation": ("OPTIONAL", "String", "Path to data containing anatomical segmentation that was used to constrain streamline termination."),
119+
"Anisotropy": ("OPTIONAL", "List", "The contents of each element of this list are described in Table 4b."),
120+
"AnglePerStep": ("OPTIONAL", "Float", "If a streamline changes tangent between successive steps of greater than this value in degrees, it is terminated."),
121+
"MinimumRadius": ("OPTIONAL", "Float", "If a streamline changes tangent between successive steps corresponding to a circle of radius smaller than this value in mm, it is terminated."),
122+
"Masks": ("OPTIONAL", "List", "List of strings corresponding to mask images; a streamline is terminated as soon as it exits the region defined by these masks."),
123+
"SatisfiedAllAcceptance": ("OPTIONAL", "Binary", "Set to True if streamlines were immediately terminated at the first vertex upon which that streamline had satisfied all acceptance criteria."),
124+
"MaximumLength": ("OPTIONAL", "Float", "Units of mm. Any streamline exceeding this length was no longer propagated."),
125+
}
126+
) }}
127+
128+
Table 4b (contents of elements of list `StreamlineTermination["Anisotropy"]`):
129+
130+
{{ MACROS___make_metadata_table(
131+
{
132+
"Metric": ("REQUIRED", "String", "Text description of the anisotropy metric mediating whether a streamline was terminated."),
133+
"Source": ("REQUIRED", "String", "Filesystem path or BIDS URI of image data from which the corresponding anisotropy metric can be extracted."),
134+
"Threshold": ("REQUIRED", "Float", "Numerical threshold applied to anisotropy metric."),
135+
}
136+
) }}
137+
138+
Table 5a (contents of the value for key `StreamlineAcceptanceCriteria`):
139+
140+
{{ MACROS___make_metadata_table(
141+
{
142+
"InclusionRegions": ("OPTIONAL", "List", "List of filesystem paths. A streamline must visit every item in this list at any location along its length in order to be deemed acceptable."),
143+
"OrderedInclusionRegions": ("OPTIONAL", "List", "List of filesystem paths. A streamline must visit every item in this list in the same sequence as the order in which they appear during streamline propagation."),
144+
"ExclusionRegions": ("OPTIONAL", "List", "List of filesystem paths. A streamline must not visit any item in this list at any location along its length."),
145+
"MinimumLength": ("OPTIONAL", "Float", "In units of mm. Any streamline shorter than this length was discarded."),
146+
"MaximumLength": ("OPTIONAL", "Float", "In units of mm. Any streamline exceeding this length was discarded."),
147+
"AnatomicalSegmentation": ("OPTIONAL", "String", "Path to data containing anatomical segmentation that influenced whether streamlines were discarded."),
148+
}
149+
) }}
150+
151+
Table 6a (contents of the value for key `StreamlineReconstructionDensity`):
152+
153+
{{ MACROS___make_metadata_table(
154+
{
155+
"Seeds": ("OPTIONAL", "Int", "Tractogram generation was terminated if this number of unique seed vertices was drawn."),
156+
"GeneratedStreamlines": ("OPTIONAL", "Int", "Tractogram generation was terminated if this number of streamlines were generated."),
157+
"AcceptedStreamlines": ("OPTIONAL", "Int", "Tractogram generation was terminated once this number of streamlines was written to the output tractogram."),
158+
}
159+
) }}
160+
161+
## Tracking methods
162+
163+
The `track` entity uses a controlled vocabulary of tracking method abbreviations,
164+
as defined in the schema `enum` for this entity:
85165

86166
{{ MACROS___make_subobject_table("metadata.Track") }}

‎src/schema/objects/metadata.yaml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4638,3 +4638,63 @@ iEEGReference:
46384638
this field should have a general description and the channel specific
46394639
reference should be defined in the `channels.tsv` file.
46404640
type: string
4641+
StreamlineSeeding:
4642+
name: StreamlineSeeding
4643+
display_name: Streamline Seeding
4644+
description: |
4645+
The specification of how streamline seed points were determined.
4646+
The contents of this dictionary are described in the
4647+
[diffusion derivatives](SPEC_ROOT/derivatives/diffusion-derivatives.md)
4648+
documentation.
4649+
type: object
4650+
StreamlinePropagation:
4651+
name: StreamlinePropagation
4652+
display_name: Streamline Propagation
4653+
description: |
4654+
The specification of how streamlines were propagated from seed points.
4655+
The contents of this dictionary are described in the
4656+
[diffusion derivatives](SPEC_ROOT/derivatives/diffusion-derivatives.md)
4657+
documentation.
4658+
type: object
4659+
StreamlineTermination:
4660+
name: StreamlineTermination
4661+
display_name: Streamline Termination
4662+
description: |
4663+
The specification of criteria that caused ongoing streamline propagation
4664+
to cease. The contents of this dictionary are described in the
4665+
[diffusion derivatives](SPEC_ROOT/derivatives/diffusion-derivatives.md)
4666+
documentation.
4667+
type: object
4668+
StreamlineAcceptanceCriteria:
4669+
name: StreamlineAcceptanceCriteria
4670+
display_name: Streamline Acceptance Criteria
4671+
description: |
4672+
The specification of criteria applied to decide whether a streamline
4673+
that was successfully propagated was acceptable to be retained in the
4674+
output tractogram. The contents of this dictionary are described in the
4675+
[diffusion derivatives](SPEC_ROOT/derivatives/diffusion-derivatives.md)
4676+
documentation.
4677+
type: object
4678+
StreamlineReconstructionDensity:
4679+
name: StreamlineReconstructionDensity
4680+
display_name: Streamline Reconstruction Density
4681+
description: |
4682+
The specification of criteria that determined when tractogram generation
4683+
ceased based on the number of seeds, generated streamlines, or accepted
4684+
streamlines. The contents of this dictionary are described in the
4685+
[diffusion derivatives](SPEC_ROOT/derivatives/diffusion-derivatives.md)
4686+
documentation.
4687+
type: object
4688+
Track:
4689+
name: Track
4690+
display_name: Tracking Method
4691+
description: |
4692+
A description of the algorithm used to perform tractography.
4693+
type: object
4694+
properties:
4695+
Name:
4696+
$ref: objects.metadata.Name
4697+
Description:
4698+
$ref: objects.metadata.Description
4699+
URL:
4700+
$ref: objects.metadata.URL

0 commit comments

Comments
 (0)