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 4 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
69 changes: 49 additions & 20 deletions src/05-derivatives/03-imaging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,16 +122,16 @@ Template:
<source_entities>[_space-<space>][_res-<label>][_den-<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`.

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. |
| 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 +153,24 @@ 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 voxel is identified with a label or a combination of labels.
effigies marked this conversation as resolved.
Show resolved Hide resolved
A *discrete segmentation* represents each tissue class with a unique integer
effigies marked this conversation as resolved.
Show resolved Hide resolved
label.
A *probabilistic segmentation* represents each tissue class as values between
0 and 1 (inclusive) at each location in the image, and one volume/frame per
tissue class are concatenated in a single file.
effigies marked this conversation as resolved.
Show resolved Hide resolved

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 Down Expand Up @@ -189,24 +204,25 @@ 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 `desc` entity SHOULD be used
effigies marked this conversation as resolved.
Show resolved Hide resolved
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_desc-GM_mask.nii.gz
effigies marked this conversation as resolved.
Show resolved Hide resolved
```

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
If a single tissue class is included the `label` entity SHOULD be used to
effigies marked this conversation as resolved.
Show resolved Hide resolved
specify the corresponding structure.

Template:
Expand Down Expand Up @@ -254,12 +270,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 +289,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 +365,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 +377,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