Imaging data types
This section pertains to imaging data, which characteristically have spatial extent and resolution.
Preprocessed, coregistered and/or resampled volumes
Template:
<pipeline_name>/
sub-<label>/
<datatype>/
<source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_<suffix>.<extension>
Volumetric preprocessing does not modify the number of dimensions, and so the specifications in Preprocessed or cleaned data apply. The use of surface meshes and volumetric measures sampled to those meshes is sufficiently similar in practice to treat them equivalently.
When two or more instances of a given derivative are provided with resolution
or surface sampling density being the only difference between them, then the
res (for resolution of regularly sampled N-D data) and/or
den (for density of non-parametric surfaces)
entities SHOULD be used to avoid name conflicts.
Note that only files combining both regularly sampled (for example, gridded)
and surface sampled data (and their downstream derivatives) are allowed
to present both res and
den entities simultaneously.
Examples:
└─ pipeline1/
└─ sub-001/
└─ func/
├─ sub-001_task-rest_run-1_space-MNI305_res-lo_bold.nii.gz
├─ sub-001_task-rest_run-1_space-MNI305_res-hi_bold.nii.gz
└─ sub-001_task-rest_run-1_space-MNI305_bold.json
The following metadata JSON fields are defined for preprocessed images:
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| SkullStripped | REQUIRED | boolean | Whether the volume was skull stripped (non-brain voxels set to zero) or not. Must be one of: "true", "false". |
| Resolution | REQUIRED if res is present |
string or object of strings | Specifies the interpretation of the resolution keyword. If an object is used, then the keys should be values for the res entity and values should be descriptions of those res values. |
| Density | REQUIRED if den is present |
string or object of strings | Specifies the interpretation of the density keyword. If an object is used, then the keys should be values for the den entity and values should be descriptions of those den values. |
Example JSON file corresponding to
pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_bold.json above:
{
"SkullStripped": true,
"Resolution": {
"hi": "Matched with high-resolution T1w (0.7mm, isotropic)",
"lo": "Matched with original BOLD resolution (2x2x3 mm^3)"
}
}
This would be equivalent to having two JSON metadata files, one
corresponding to res-lo
(pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-lo_bold.json):
{
"SkullStripped": true,
"Resolution": "Matched with original BOLD resolution (2x2x3 mm^3)"
}
And one corresponding to res-hi
(pipeline1/sub-001/func/sub-001_task-rest_run-1_space-MNI305_res-hi_bold.json):
{
"SkullStripped": true,
"Resolution": "Matched with high-resolution T1w (0.7mm, isotropic)"
}
Example of CIFTI-2 files (a format that combines regularly sampled data
and non-parametric surfaces) having both res
and den entities:
└─ pipeline1/
└─ sub-001/
└─ func/
├─ sub-001_task-rest_run-1_space-fsLR_res-1_den-10k_bold.dtseries.nii
├─ sub-001_task-rest_run-1_space-fsLR_res-1_den-41k_bold.dtseries.nii
├─ sub-001_task-rest_run-1_space-fsLR_res-2_den-10k_bold.dtseries.nii
├─ sub-001_task-rest_run-1_space-fsLR_res-2_den-41k_bold.dtseries.nii
└─ sub-001_task-rest_run-1_space-fsLR_bold.json
And the corresponding sub-001_task-rest_run-1_space-fsLR_bold.json file:
{
"SkullStripped": true,
"Resolution": {
"1": "Matched with MNI152NLin6Asym 1.6mm isotropic",
"2": "Matched with MNI152NLin6Asym 2.0mm isotropic"
},
"Density": {
"10k": "10242 vertices per hemisphere (5th order icosahedron)",
"41k": "40962 vertices per hemisphere (6th order icosahedron)"
}
}
Masks
Template:
<pipeline_name>/
sub-<label>/
anat|func|dwi/
<source_entities>[_space-<space>][_res-<label>][_den-<label>][_label-<label>][_desc-<label>]_mask.nii.gz
A binary (1 - inside, 0 - outside) mask in the space defined by the space entity.
If no transformation has taken place, the value of space SHOULD be set to orig.
If the mask is an ROI mask derived from an atlas segmentation,
then the label entity SHOULD be used to specify the masked structure
(see Common image-derived labels).
JSON metadata fields:
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Type | RECOMMENDED | 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. Must be one of: "Brain", "Lesion", "Face", "ROI". |
| Sources | RECOMMENDED | 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. |
| RawSources | DEPRECATED | array of strings | A list of paths relative to dataset root pointing to the BIDS-Raw file(s) that were used in the creation of this derivative. This field is DEPRECATED, and this metadata SHOULD be recorded in the Sources field using BIDS URIs to distinguish sources from different datasets. |
| Resolution | REQUIRED if res is present |
string or object of strings | Specifies the interpretation of the resolution keyword. If an object is used, then the keys should be values for the res entity and values should be descriptions of those res values. |
| Density | REQUIRED if den is present |
string or object of strings | Specifies the interpretation of the density keyword. If an object is used, then the keys should be values for the den entity and values should be descriptions of those den values. |
Examples:
└─ func_loc/
└─ sub-001/
└─ func/
├─ sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.nii.gz
└─ sub-001_task-rest_run-1_space-MNI305_desc-PFC_mask.json
└─ manual_masks/
└─ sub-001/
└─ anat/
├─ sub-001_desc-tumor_mask.nii.gz
└─ sub-001_desc-tumor_mask.json
Segmentations
A segmentation is a labeling of regions of an image such that each location (for example, a voxel or a surface vertex) is identified with a label or a combination of labels. Labeled regions may include anatomical structures (such as tissue class, Brodmann area or white matter tract), discontiguous, functionally-defined networks, tumors or lesions.
A discrete segmentation represents each region with a unique integer label. A probabilistic segmentation represents each region as values between 0 and 1 (inclusive) at each location in the image, and one volume/frame per structure may be concatenated in a single file.
Segmentations may be defined in a volume (labeled voxels), a surface (labeled vertices) or a combined volume/surface space.
If the segmentation can be generated in different ways,
for example, following an atlas segmentation,
the seg entity MAY be used to
distinguish the name of the segmentation used.
The following section describes discrete and probabilistic segmentations of volumes, followed by discrete segmentations of surface/combined spaces. Probabilistic segmentations of surfaces are currently unspecified.
The following metadata fields apply to all segmentation files:
| Key name | Requirement Level | Data type | Description |
|---|---|---|---|
| Manual | OPTIONAL | boolean | Indicates if the segmentation was performed manually or via an automated process. Must be one of: "true", "false". |
| Resolution | REQUIRED if res is present |
string or object of strings | Specifies the interpretation of the resolution keyword. If an object is used, then the keys should be values for the res entity and values should be descriptions of those res values. |
| Density | REQUIRED if den is present |
string or object of strings | Specifies the interpretation of the density keyword. If an object is used, then the keys should be values for the den entity and values should be descriptions of those den values. |
Discrete Segmentations
Discrete segmentations of brain tissue represent multiple anatomical structures (such as tissue class or Brodmann area) with a unique integer label in a 3D volume. See Common image-derived labels for a description of how integer values map to anatomical structures.
Template:
<pipeline_name>/
sub-<label>/
anat|func|dwi/
<source_entities>[_space-<space>][_seg-<label>][_res-<label>][_den-<label>]_dseg.nii.gz
Example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_space-orig_dseg.nii.gz
└─ sub-001_space-orig_dseg.json
A segmentation can be used to generate a binary mask that functions as a
discrete "label" for a single structure.
In this case, the mask suffix MUST be used,
the label entity) SHOULD be used
to specify the masked structure
(see Common image-derived labels),
and the seg entity SHOULD be defined.
For example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_space-orig_seg-Desikan_label-GM_mask.nii.gz
└─ sub-001_space-orig_seg-Desikan_label-GM_mask.json
Probabilistic Segmentations
Probabilistic segmentations of brain tissue represent a single anatomical
structure with values ranging from 0 to 1 in individual 3D volumes or across
multiple frames.
If a single structure is included,
the label entity SHOULD be used to specify
the structure.
Template:
<pipeline_name>/
sub-<label>/
func|anat|dwi/
<source_entities>[_space-<space>][_seg-<label>][_res-<label>][_den-<label>][_label-<label>]_probseg.nii.gz
Example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_space-orig_label-BG_probseg.nii.gz
└─ sub-001_space-orig_label-WM_probseg.nii.gz
See Common image-derived labels
for reserved values for the label entity.
A 4D probabilistic segmentation, in which each frame corresponds to a different tissue class, must provide a label mapping in its JSON sidecar. For example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_space-orig_probseg.nii.gz
└─ sub-001_space-orig_probseg.json
The JSON sidecar MUST include the label-map key that specifies a tissue label for each volume:
{
"LabelMap": [
"BG",
"WM",
"GM"
]
}
Values of label SHOULD correspond to abbreviations defined in
Common image-derived labels.
Discrete surface segmentations
Discrete surface segmentations (sometimes called parcellations) of cortical
structures MUST be stored as GIFTI label files, with the extension .label.gii.
For combined volume/surface spaces, discrete segmentations MUST be stored as
CIFTI-2 dense label files, with the extension .dlabel.nii.
Template:
<pipeline_name>/
sub-<label>/
anat/
<source_entities>[_hemi-{L|R}][_space-<space>][_seg-<label>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
The hemi-<label> entity is REQUIRED for GIFTI files storing information about
a structure that is restricted to a hemibrain.
For example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_hemi-L_dseg.label.gii
└─ sub-001_hemi-R_dseg.label.gii
The REQUIRED extension for CIFTI parcellations is .dlabel.nii. For example:
└─ pipeline/
└─ sub-001/
└─ anat/
└─ sub-001_dseg.dlabel.nii
Common image-derived labels
BIDS supplies a standard, generic label-index mapping, defined in the table below, that contains common image-derived segmentations and can be used to map segmentations (and parcellations) between lookup tables.
| Integer value | Description | Abbreviation (label) |
|---|---|---|
| 0 | Background | BG |
| 1 | Gray Matter | GM |
| 2 | White Matter | WM |
| 3 | Cerebrospinal Fluid | CSF |
| 4 | Bone | B |
| 5 | Soft Tissue | ST |
| 6 | Non-brain | NB |
| 7 | Lesion | L |
| 8 | Cortical Gray Matter | CGM |
| 9 | Subcortical Gray Matter | SGM |
| 10 | Brainstem | BS |
| 11 | Cerebellum | CBM |
These definitions can be overridden (or added to) by providing custom labels in
a sidecar <matches>.tsv file, in which <matches> corresponds to segmentation
filename.
Example:
└─ pipeline/
└─ sub-001/
└─ anat/
├─ sub-001_space-orig_dseg.nii.gz
└─ sub-001_space-orig_dseg.tsv
Definitions can also be specified with a top-level dseg.tsv, which propagates to
segmentations in relative subdirectories.
Example:
└─ pipeline/
├─ dseg.tsv
└─ sub-001/
└─ anat/
└─ sub-001_space-orig_dseg.nii.gz
These TSV lookup tables contain the following columns:
| Column name | Requirement Level | Data type | Description |
|---|---|---|---|
| index | REQUIRED | integer | The label integer index. Values in index MUST be unique. |
| name | REQUIRED | string | The unique label name. |
| abbreviation | OPTIONAL | string | The unique label abbreviation |
| color | OPTIONAL | string | Hexadecimal. Label color for visualization. |
| mapping | OPTIONAL | integer | Corresponding integer label in the standard BIDS label lookup. |
| Additional Columns | NOT ALLOWED | n/a |
Additional columns are not allowed. |
An example, custom dseg.tsv that defines three labels:
index name abbreviation color mapping
100 Gray Matter GM #ff53bb 1
101 White Matter WM #2f8bbe 2
102 Brainstem BS #36de72 11
The following example dseg.tsv defines regions that are not part of the
standard BIDS labels:
index name abbreviation
137 pars opercularis IFGop
138 pars triangularis IFGtr
139 pars orbitalis IFGor