Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[ENH] Clarify mask/dseg/probseg in common derivatives #489

Merged
merged 6 commits into from
Jun 1, 2020
Merged

[ENH] Clarify mask/dseg/probseg in common derivatives #489

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9eca762
ENH: Change single ROI binary image suffix from dseg to mask
effigies May 30, 2020
8afb695
Improve wording
effigies May 30, 2020
d820af2
Clarify discrete surface segmentations
effigies May 30, 2020
a3a8d69
Swap mapping/color and add an example dseg with new labels
effigies May 30, 2020
0f3d9ab
Replace "tissue class" with more general "anatomical structure"
effigies May 31, 2020
a7f22b2
Add labels for masks
effigies May 31, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 62 additions & 27 deletions src/05-derivatives/03-imaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,19 +119,22 @@ Template:
<pipeline_name>/
sub-<participant_label>/
anat|func|dwi/
<source_entities>[_space-<space>][_res-<label>][_den-<label>][_desc-<label>]_mask.nii.gz
<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 `<space>`. By
default (i.e., if no transformation has taken place) the value of `space` should
be set to `orig`.
A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
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, then the `label` entity SHOULD
be used to specify the masked structure (see [Anatomical labels](#anatomical-labels),
and the `Atlas` metadata SHOULD be defined.

JSON metadata fields:

| **Key name** | **Description** |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| RawSources | Same as defined in [Introduction][intro], but elevated from OPTIONAL to REQUIRED |
| Type | RECOMMENDED. Short identifier of the mask. Reserved values: `Brain` - brain mask, `Lesion` - lesion mask, `Face` - face mask, `ROI` - ROI mask |
| Atlas | OPTIONAL. Which atlas (if any) was used to generate the mask. RECOMMENDED if `label` entity is defined. |
| Resolution | REQUIRED if `res` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the resolution keyword. |
| Density | REQUIRED if `den` is present. String, or [object][] mapping labels to strings. Specifies the interpretation of the density keyword. |

Expand All @@ -153,9 +156,25 @@ manual_masks/
sub-001_desc-tumor_mask.json
```

## Segmentations and parcellations
## Segmentations

Common JSON metadata fields:
A *segmentation* is a labeling of a spatial image with anatomical structures
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A *segmentation* is a labeling of a spatial image with anatomical structures
A *segmentation* is a labeling of the samples in a signal encoding a partition of interest
(e.g., the spatial delineation of anatomical structures in a 2D or 3D image)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the concept of segmentation is valid for 1D signals too. I'm fine having all of this under imaging for practical reasons (i.e., finalize a first release of derivatives), but the definition could/should be general (IMHO).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this suggestion really hard to parse.

Are there examples of 1D signals that will be segmented in neuroimaging that really motivates this? I can try to offer some wording that would cover those cases.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Epilepsy EEG markup where there are multiple different seizure types? This is coming from no familiarity with EEG BIDS whatsoever; it just came to mind.

Another might be a discrete fixel-based parcellation; but whether such data are 1D or 4D is a matter of perspective 🙃

such that each location (for example, a voxel or a surface vertex) is identified
with a label or a combination of labels.
A *discrete segmentation* represents each structure with a unique integer
label.
A *probabilistic segmentation* represents each structure 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.
Comment on lines +164 to +168
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I'm gonna poke at this again 😬

This is technically another location where there are two different concepts getting mushed together (yes, that is the technical term):

  • How are multiple segmented structures represented in a single file?
    • Within a single volume
    • Across volumes
  • What data type is used to represent the segmentation?
    • Binary
    • Floating-point

For continuous / "probabilistic" data, storing multiple structures in a single volume is impossible, and so necessitates storing them across volumes.

For discrete data, we're accustomed to such being represented in a single volume / frame, using unique integer labels. This however enforces a one-to-one mapping between "elements" (e.g. voxels, vertices) and labels. In some instances (TractSeg comes to mind, as well as internal developments here), it's possible for one voxel to be included in multiple binary segmentations, at which point using unique integer labels does not work and one would need a 4D image.

(In a way this could be thought of as a 4D _mask.nii[.gz] image as opposed to / in addition to a _dseg image...)

I don't actually have a fixed opinion on what to do here (if anything); just seeing if the spec can be made to cover the fundamentals, rather than unnecessarily excluding anything that strays slightly from the current most common use cases.


Segmentations may be defined in a volume (labeled voxels), a surface (labeled
vertices) or a combined volume/surface space.

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** | **Description** |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
Expand All @@ -166,9 +185,10 @@ Common JSON metadata fields:

### Discrete Segmentations

Discrete segmentations of brain tissue represent each tissue class with a unique
integer label in a 3D volume. See [Anatomical Labels](#anatomical-labels) for interpretation how
integer values map to tissue classes.
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 [Anatomical Labels](#anatomical-labels) for interpretation how integer values
map to anatomical structures.
Comment on lines +190 to +191
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
See [Anatomical Labels](#anatomical-labels) for interpretation how integer values
map to anatomical structures.
See [Anatomical Labels](#anatomical-labels) for interpretation regarding how
integer values map to anatomical structures.


Template:

Expand All @@ -189,25 +209,27 @@ pipeline/
sub-001_space-orig_dseg.json
```

A segmentation could be a binary mask that functions as a discrete `label` for a
single structure. In this case, the label key must be used to specify the
corresponding structure. For example:
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, and the `label` entity SHOULD be used
to specify the masked structure (see [Anatomical labels](#anatomical-labels), and
the `Atlas` metadata SHOULD be defined.
For example:

```Text
pipeline/
sub-001/
anat/
sub-001_space-orig_label-GM_dseg.nii.gz
sub-001_space-orig_label-GM_mask.nii.gz
```

See [Anatomical Labels](#anatomical-labels) for reserved key values for `label`.

### Probabilistic Segmentations

Probabilistic segmentations of brain tissue represent a single tissue class with
values ranging from 0 to 1 in individual 3D volumes or across multiple frames.
Similarly to a discrete, binary segmentation, the label key can be used to
specify the corresponding structure.
Probabilistic segmentations of brain tissue represent a single anatomical
structure with values ranging from 0 to 1 in individual 3D volumes or across
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
structure with values ranging from 0 to 1 in individual 3D volumes or across
structure with values in the range `[0.0,1.0]` in individual 3D volumes or across

(trying to indicate the the indicated range is inclusive of the bounding values)

multiple frames.
If a single structure is included the `label` entity SHOULD be used to specify
the structure.

Template:

Expand Down Expand Up @@ -254,12 +276,15 @@ for each volume:
}
```

Values of `label` need to map to Abbreviations defined in [Anatomical Labels](#anatomical-labels).
Values of `label` SHOULD correspond to abbreviations defined in
[Anatomical Labels](#anatomical-labels).

### Surface Parcellations
### Discrete surface segmentations

Discrete parcellations (surface segmentations) of cortical structures should be
stored as GIFTI or CIFTI file.
Discrete surface segmentations (sometimes called *parcellations*) of cortical
structures MUST be stored as GIFTI label files, with extension `.label.gii`.
For combined volume/surface spaces, discrete segmentations MUST be stored as
CIFTI-2 dense label fles, with extension `.dlabel.nii`.

Template:

Expand All @@ -270,8 +295,7 @@ Template:
<source_entities>[_hemi-{L|R}][_space-<space>][_res-<label>][_den-<label>]_dseg.{label.gii|dlabel.nii}
```

The REQUIRED extension for GIFTI parcellations is `.label.gii`. The `hemi` tag is
REQUIRED for GIFTI files. For example:
The `hemi` tag is REQUIRED for GIFTI files. For example:

```Text
pipeline/
Expand Down Expand Up @@ -347,10 +371,10 @@ These TSV lookup tables contain the following columns:
| index | REQUIRED. The label integer index |
| name | REQUIRED. The unique label name |
| abbreviation | OPTIONAL. The unique label abbreviation |
| mapping | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |
| color | OPTIONAL. Hexadecimal. Label color for visualization |
| mapping | OPTIONAL. Corresponding integer label in the standard BIDS label lookup |

An example, custom dseg.tsv that defines three labels:
An example, custom `dseg.tsv` that defines three labels:

```Text
index name abbreviation color mapping
Expand All @@ -359,10 +383,21 @@ index name abbreviation color mapping
102 Brainstem BS #36de72 11
```

The following example `dseg.tsv` defines regions that are not part of the
standard BIDS labels:

```Text
index name abbreviation
137 pars opercularis IFGop
138 pars triangularis IFGtr
139 pars orbitalis IFGor
```

[]: <> (################)
[]: <> (Link definitions)
[]: <> (################)

[intro]: 01-introduction.md
[common_preproc]: 02-common-data-types.md#preprocessed-or-cleaned-data
[object]: https://www.json.org/json-en.html
[unspecified]: ../02-common-principles.md#unspecified-data