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

[ENH] Add part entity for complex-valued data #424

Merged
merged 40 commits into from
Nov 23, 2020
Merged

[ENH] Add part entity for complex-valued data #424

Show file tree
Hide file tree
Changes from 38 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
d9d2324
Add part entity.
tsalo Feb 24, 2020
35c0253
Add self to contributors file.
tsalo Feb 25, 2020
239c338
Address @yarikoptic's review.
tsalo May 4, 2020
82f60fd
Fix entity table spacing.
tsalo May 5, 2020
6bcc2a5
Add missing OPTIONAL for part under func (bold phase).
tsalo May 5, 2020
69ea608
Fix spacing again.
tsalo May 5, 2020
2f67010
Remove OPTIONAL under func (bold phase). Wasn't missing.
tsalo May 6, 2020
3c222d1
Fix entity order (part goes after run).
tsalo May 18, 2020
eca38ef
Merge branch 'master' into enh/part-entity
tsalo May 20, 2020
2f65a94
Merge branch 'master' into enh/part-entity
tsalo Jun 20, 2020
908bdba
Fix typo.
tsalo Jun 20, 2020
6d376e4
Merge branch 'master' into enh/part-entity
tsalo Aug 24, 2020
3ca9763
Incorporate part into schema.
tsalo Aug 24, 2020
f566cf4
Update definition and examples to match BEP001.
tsalo Aug 24, 2020
d6dc2ac
Fix code snippets.
tsalo Aug 24, 2020
8db0dea
Fix filename patterns now that real/imag is supported.
tsalo Aug 24, 2020
85957a3
Apply suggestions from code review
tsalo Sep 1, 2020
0a88998
Support part with BOLD and update entity table.
tsalo Sep 1, 2020
08a0934
Update src/04-modality-specific-files/01-magnetic-resonance-imaging-d…
tsalo Sep 1, 2020
01df45c
Merge branch 'master' into enh/part-entity
tsalo Sep 8, 2020
c46715f
Update entity table and entity definitions.
tsalo Sep 8, 2020
44a1a35
Add link in text.
tsalo Sep 8, 2020
8561f4a
Remove section header.
tsalo Sep 8, 2020
78aad5a
Address review.
tsalo Sep 18, 2020
7655333
Merge branch 'master' into enh/part-entity
tsalo Oct 2, 2020
eb1f95f
Update src/04-modality-specific-files/01-magnetic-resonance-imaging-d…
tsalo Oct 3, 2020
e0ffe84
Deprecate phase suffix.
tsalo Oct 16, 2020
d800c09
Fix link.
tsalo Oct 16, 2020
9027334
Fix link again.
tsalo Oct 16, 2020
a8f54a1
Include deprecation in table.
tsalo Oct 16, 2020
f04f195
Fix table.
tsalo Oct 16, 2020
72800d1
Update 01-magnetic-resonance-imaging-data.md
tsalo Oct 16, 2020
28abc54
Apply suggestions from code review
tsalo Nov 16, 2020
5903d5d
Add entity field.
tsalo Nov 16, 2020
cde2337
Merge branch 'master' into enh/part-entity
tsalo Nov 16, 2020
21aed29
Fix bug and generate appendix.
tsalo Nov 16, 2020
e914b91
Fix table.
tsalo Nov 17, 2020
903324b
Update src/04-modality-specific-files/01-magnetic-resonance-imaging-d…
tsalo Nov 17, 2020
78e70ef
Improve part definition.
tsalo Nov 17, 2020
a68fc79
Merge branch 'master' into enh/part-entity
effigies Nov 19, 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
84 changes: 69 additions & 15 deletions src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
View file
Open in desktop
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,36 @@ 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 `mag/phase` or `real/imag` pairs.
tsalo marked this conversation as resolved.
Show resolved Hide resolved
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 +233,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 +314,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 +443,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
Open in desktop
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