Diffusion derivatives
Diffusion-based tractography
Tractography based on diffusion-weighted MRI data is stored as streamlines in the TRX file format:
<pipeline_name>/
sub-<label>/
[ses-<label>/]
<modality>/
<source-entities>[space-<space>]_[tract-<tract name>]_[track-<tracking method>]_tractogram.trx
<source-entities>[space-<space>]_[tract-<tract name>]_[track-<tracking method>]_tractogram.json
Where tract is the anatomical/structural entity that is being imaged, and
track is fully specified in the sidecar as described below.
For the most common case, a tractogram will be generated from some DWI data, so
For example:
pyAFQ/
sub–01/
dwi/
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.trx
sub-01_space-MNI152NLin2009cAsym_tract-wholebrain_track-eudx_tractogram.json
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.trx
sub-01_space-MNI152NLin2009cAsym_tract-ArcuateFasciculus_hemi-L_track-eudx_tractogram.json
The JSON sidecar accompanying the tractogram contains the following metadata fields:
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Name | OPTIONAL | string | Name of the dataset. A human-readable name corresponding to the primary tractography algorithm and/or software used to generate the streamlines data. |
| Description | OPTIONAL | string | Free-form natural language description. A longer description of the nature of the tractography experiment |
| URL | OPTIONAL | string | A Uniform Resource Locator (URL) is a structured reference to an object that includes a resource transfer scheme and a location. (see URI) 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. |
| StreamlineSeeding | REQUIRED | object | The specification of how streamline seed points were determined. The contents of this dictionary are described in the diffusion derivatives documentation. The contents of this dictionary are described in Table 2a. |
| StreamlinePropagation | REQUIRED | object | The specification of how streamlines were propagated from seed points. The contents of this dictionary are described in the diffusion derivatives documentation. The contents of this dictionary are described in Table 3a. |
| StreamlineTermination | REQUIRED | object | The specification of criteria that caused ongoing streamline propagation to cease. The contents of this dictionary are described in the diffusion derivatives documentation. The contents of this dictionary are described in Table 4a. |
| StreamlineAcceptanceCriteria | REQUIRED | object | The specification of criteria applied to decide whether a streamline that was successfully propagated was acceptable to be retained in the output tractogram. The contents of this dictionary are described in the diffusion derivatives documentation. The contents of this dictionary are described in Table 5a. |
| StreamlineReconstructionDensity | OPTIONAL | object | The specification of criteria that determined when tractogram generation ceased based on the number of seeds, generated streamlines, or accepted streamlines. The contents of this dictionary are described in the diffusion derivatives documentation. The contents of this dictionary are described in Table 6a. |
Table 2a (contents of the value for key StreamlineSeeding)
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Sources | REQUIRED | array of strings | A list of files with the paths specified using BIDS URIs; these files were directly used in the creation of this derivative data file. For example, if a derivative A is used in the creation of another derivative B, which is in turn used to generate C in a chain of A->B->C, C should only list B in "Sources", and B should only list A in "Sources". However, in case both X and Y are directly used in the creation of Z, then Z should list X and Y in "Sources", regardless of whether X was used to generate Y. Using paths specified relative to the dataset root is DEPRECATED. 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 |
| nan | nan | nan | nan |
Table 2b (contents of elements within list StreamlineSeeding["Sources"]):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Type | REQUIRED | string | Short identifier of the mask. The value "Brain" refers to a brain mask. The value "Lesion" refers to a lesion mask. The value "Face" refers to a face mask. The value "ROI" refers to a region of interest mask. Selection from the following: ['Random', 'Sphere', 'RandomPerElement', 'GridPerElement', 'CountPerElement', 'RejectionSampling', 'Dynamic']. 'Element' can refer to voxels, fixels, or surface vertex elements based on the filepath referenced by key 'Source'. 'CountPerElement' is interpreted as being, for example, seeding some number of streamlines from precisely the center of each image element, as opposed to other mechanisms that, for each image element, spread the seeds out within the volume ascribed to that image element.Must be one of: "Brain", "Lesion", "Face", "ROI". |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 2c (contents of elements of dict StreamlineSeeding["AcceptanceCriteria"]):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 2d (contents of elements of dict StreamlineSeeding["InitialDirection"]):
TODO
Table 3a (contents of the value for key StreamlinePropagation):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 3b (contents of dict StreamlinePropagation["Algorithm"]):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Name | REQUIRED | string | Name of the dataset. A human-readable name corresponding to the tractography algorithm used to generate the streamlines. |
| Description | OPTIONAL | string | Free-form natural language description. A longer description of the nature of the tractography algorithm. |
| URL | OPTIONAL | string | A Uniform Resource Locator (URL) is a structured reference to an object that includes a resource transfer scheme and a location. (see URI) A web link to a more exhaustive description of the algorithm used to generate the tractography data. |
Table 4a (contents of the value for key StreamlineTermination):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 4b (contents of elements of list StreamlineTermination["Anisotropy"]):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 5a (contents of the value for key StreamlineAcceptanceCriteria):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Table 6a (contents of the value for key StreamlineReconstructionDensity):
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| nan | nan | nan | nan |
| nan | nan | nan | nan |
| nan | nan | nan | nan |
Tracking methods
The track entity uses a controlled vocabulary of tracking method abbreviations,
as defined in the schema enum for this entity:
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Name | OPTIONAL | string | Name of the dataset. |
| Description | OPTIONAL | string | Free-form natural language description. |
| URL | OPTIONAL | string | A Uniform Resource Locator (URL) is a structured reference to an object that includes a resource transfer scheme and a location. (see URI) |