Skip to content

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