Skip to content

Commit

Permalink
[ENH] Add part entity for complex-valued data (#424)
Browse files Browse the repository at this point in the history 
* Add part entity.

* Add self to contributors file.

* Address @yarikoptic's review.

* Fix entity table spacing.

* Add missing OPTIONAL for part under func (bold phase).

* Fix spacing again.

* Remove OPTIONAL under func (bold phase). Wasn't missing.

* Fix entity order (part goes after run).

* Fix typo.

* Incorporate part into schema.

* Update definition and examples to match BEP001.

* Fix code snippets.

* Fix filename patterns now that real/imag is supported.

* Apply suggestions from code review

- Change radians to rad.
- Treat `part` like `run`. Can only be omitted if only magnitude image is provided.

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Support part with BOLD and update entity table.

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Update entity table and entity definitions.

* Add link in text.

* Remove section header.

* Address review.

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

* Deprecate phase suffix.

* Fix link.

* Fix link again.

* Include deprecation in table.

* Fix table.

* Update 01-magnetic-resonance-imaging-data.md

* Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Add entity field.

* Fix bug and generate appendix.

* Fix table.

* Update src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Improve part definition.

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Chris Markiewicz <markiewicz@stanford.edu>
  • Loading branch information
@tsalo @effigies
3 people authored Nov 23, 2020
1 parent f2545fe commit addbdde
Show file tree
Hide file tree
Showing 7 changed files with 145 additions and 28 deletions.
85 changes: 70 additions & 15 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ Template:
```Text
sub-<label>/[ses-<label>/]
anat/
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_<modality_label>.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_part-<label>]_<modality_label>.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<label>]_defacemask.nii[.gz]
```

Expand Down Expand Up @@ -195,6 +195,37 @@ fields specific to anatomical scans:
| ----------------------- | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| ContrastBolusIngredient | OPTIONAL | [string][] | Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. |

The [`part-<label>`](../99-appendices/09-entities.md#part) key/value pair is
used to indicate which component of the complex representation of the MRI
signal is represented in voxel data.
This entity is associated with the DICOM tag `0008,9208`.
Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
which are typically used in `part-mag`/`part-phase` or `part-real`/`part-imag`
pairs of files.
For example:

```Text
sub-01_part-mag_T1w.nii.gz
sub-01_part-mag_T1w.json
sub-01_part-phase_T1w.nii.gz
sub-01_part-phase_T1w.json
```

Phase images MAY be in radians or in arbitrary units.
The sidecar JSON file MUST include the units of the `phase` image.
The possible options are `rad` or `arbitrary`.
For example:

sub-01_part-phase_T1w.json

```Text
{
"Units": "rad"
}
```

When there is only a magnitude image of a given type, the `part` key MAY be omitted.

Similarly, the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).
Expand All @@ -203,19 +234,20 @@ different reconstruction algorithms (for example ones using motion correction).

Currently supported image contrasts include:

| **Name** | `contrast_label` | **Description** |
|---------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| BOLD | bold | Blood-Oxygen-Level Dependent contrast (specialized T2\* weighting) |
| CBV | cbv | Cerebral Blood Volume contrast (specialized T2\* weighting or difference between T1 weighted images) |
| Phase | phase | Phase information associated with magnitude information stored in BOLD contrast |
| **Name** | `suffix` | **Description** |
|---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| BOLD | bold | Blood-Oxygen-Level Dependent contrast (specialized T2\* weighting) |
| CBV | cbv | Cerebral Blood Volume contrast (specialized T2\* weighting or difference between T1 weighted images) |
| Phase | phase | [DEPRECATED](../02-common-principles.md#definitions). Phase information associated with magnitude information stored in BOLD contrast. This suffix should be replaced by the [`part-phase`](../99-appendices/09-entities.md#part) in conjunction with the `bold` suffix. |

Template:

```Text
sub-<label>/[ses-<label>/]
func/
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_sbref.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<label>]_bold.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<label>]_cbv.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<label>]_sbref.nii[.gz]
```

Functional imaging consists of techniques that support rapid temporal repetition.
Expand Down Expand Up @@ -283,7 +315,30 @@ Please note that the `<index>` denotes the number/index (in the form of a
nonnegative integer) of the echo not the echo time value which needs to be stored in the
field EchoTime of the separate JSON file.

Some meta information about the acquisition MUST be provided in an additional
Complex-valued data MUST be split into one file for each data type.
For BOLD data, there are separate suffixes for magnitude (`_bold`) and phase
(`_phase`) data, but the `_phase` suffix is [deprecated](../02-common-principles.md#definitions).
Newly generated datasets SHOULD NOT use the `_phase` suffix, and the suffix will be removed
from the specification in the next major release.
For backwards compatibility, `_phase` is considered equivalent to `_part-phase_bold`.
When the `_phase` suffix is not used, each file shares the same
name with the exception of the `part-<mag|phase>` or `part-<real|imag>` key/value.
For example:

```Text
sub-01/
func/
sub-01_task-cuedSGT_part-mag_bold.nii.gz
sub-01_task-cuedSGT_part-mag_bold.json
sub-01_task-cuedSGT_part-phase_bold.nii.gz
sub-01_task-cuedSGT_part-phase_bold.json
sub-01_task-cuedSGT_part-mag_sbref.nii.gz
sub-01_task-cuedSGT_part-mag_sbref.json
sub-01_task-cuedSGT_part-phase_sbref.nii.gz
sub-01_task-cuedSGT_part-phase_sbref.json
```

Some meta information about the acquisition MUST be provided in an additional
JSON file.

### Required fields
Expand Down Expand Up @@ -389,12 +444,12 @@ Template:
```Text
sub-<label>/[ses-<label>/]
dwi/
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.bval
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.bvec
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_dwi.json
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_sbref.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>]_sbref.json
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_dwi.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_dwi.bval
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_dwi.bvec
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_dwi.json
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_sbref.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_dir-<label>][_run-<index>][_part-<label>]_sbref.json
```

If more than one run of the same acquisition and direction has been acquired, the
Expand Down
21 changes: 11 additions & 10 deletions src/99-appendices/04-entity-table.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,17 @@ while entity definitions are in [Appendix IX](09-entities.md).

## Magnetic Resonance Imaging

| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding Modality | Echo | Recording |
|------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|-------------------------------------|-----------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|-------------------------------------------------|
| Format | [`sub-<label>`](09-entities.md#sub) | [`ses-<label>`](09-entities.md#ses) | [`task-<label>`](09-entities.md#task) | [`acq-<label>`](09-entities.md#acq) | [`ce-<label>`](09-entities.md#ce) | [`rec-<label>`](09-entities.md#rec) | [`dir-<label>`](09-entities.md#dir) | [`run-<index>`](09-entities.md#run) | [`mod-<label>`](09-entities.md#mod) | [`echo-<index>`](09-entities.md#echo) | [`recording-<label>`](09-entities.md#recording) |
| anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | |
| anat<br>(defacemask) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | OPTIONAL | | |
| dwi<br>(dwi sbref) | REQUIRED | OPTIONAL | | OPTIONAL | | | OPTIONAL | OPTIONAL | | | |
| fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap) | REQUIRED | OPTIONAL | | OPTIONAL | | | | OPTIONAL | | | |
| fmap<br>(epi) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | | REQUIRED | OPTIONAL | | | |
| func<br>(bold cbv phase sbref events) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | |
| func<br>(physio stim) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | | | OPTIONAL |
| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding Modality | Echo | Recording | Part |
|------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|-------------------------------------|-----------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|-------------------------------------|---------------------------------------|-------------------------------------------------|---------------------------------------|
| Format | [`sub-<label>`](09-entities.md#sub) | [`ses-<label>`](09-entities.md#ses) | [`task-<label>`](09-entities.md#task) | [`acq-<label>`](09-entities.md#acq) | [`ce-<label>`](09-entities.md#ce) | [`rec-<label>`](09-entities.md#rec) | [`dir-<label>`](09-entities.md#dir) | [`run-<index>`](09-entities.md#run) | [`mod-<label>`](09-entities.md#mod) | [`echo-<index>`](09-entities.md#echo) | [`recording-<label>`](09-entities.md#recording) | [`part-<label>`](09-entities.md#part) |
| anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | | OPTIONAL |
| anat<br>(defacemask) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | OPTIONAL | | | |
| dwi<br>(dwi sbref) | REQUIRED | OPTIONAL | | OPTIONAL | | | OPTIONAL | OPTIONAL | | | | OPTIONAL |
| fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap) | REQUIRED | OPTIONAL | | OPTIONAL | | | | OPTIONAL | | | | |
| fmap<br>(epi) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | | REQUIRED | OPTIONAL | | | | |
| func<br>(bold cbv sbref) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | OPTIONAL |
| func<br>(phase events) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | |
| func<br>(physio stim) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | | | OPTIONAL | |

## Encephalography (EEG, iEEG, and MEG)

Expand Down
Loading

0 comments on commit addbdde

Please sign in to comment.