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 coil entity for uncombined MR data #425

Closed
wants to merge 21 commits into from
Closed

[ENH] Add coil entity for uncombined MR data #425

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
71fa233
Add channel (ch) entity.
tsalo Feb 25, 2020
7426d1f
Incorporate some of @yarikoptic's suggestions.
tsalo Feb 27, 2020
4acd8a7
Align table columns.
tsalo May 8, 2020
b2e7166
Change ch-<index> to ch-<label>.
tsalo May 18, 2020
f2d0882
Merge remote-tracking branch 'upstream/master' into enh/ch-entity
tsalo Aug 23, 2020
9a419ec
Add ch to schema.
tsalo Aug 23, 2020
84a5c16
Fix up line lengths.
tsalo Aug 23, 2020
f5b6468
Remove duplicate paragraph.
tsalo Aug 23, 2020
b12b83e
'ch' --> 'coil'
tsalo Aug 23, 2020
be40a4c
Merge branch 'master' into enh/ch-entity
tsalo Sep 8, 2020
7a6ade8
Update entity table and entity definitions.
tsalo Sep 8, 2020
db26730
Add in-text links.
tsalo Sep 8, 2020
831ef11
Merge branch 'master' into enh/ch-entity
tsalo Jul 9, 2021
5776a1f
Fix entity definition.
tsalo Jul 9, 2021
264da31
Fix Latin.
tsalo Jul 9, 2021
f5871db
Fix Latin again.
tsalo Jul 9, 2021
135c85d
Merge branch 'master' into enh/ch-entity
tsalo Jul 13, 2021
be135f8
Define CoilString field in the schema.
tsalo Jul 14, 2021
32a3ced
Merge branch 'master' into enh/ch-entity
tsalo Sep 7, 2021
a374ae0
Merge remote-tracking branch 'upstream/master' into enh/ch-entity
tsalo Jul 29, 2022
5d23333
Add coil to rules file.
tsalo Jul 29, 2022
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
22 changes: 18 additions & 4 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 @@ -21,6 +21,7 @@ by Ben Inglis:
| MagneticFieldStrength | RECOMMENDED. Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 `Magnetic Field Strength` |
| ReceiveCoilName | RECOMMENDED. Information describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field |
| ReceiveCoilActiveElements | RECOMMENDED. Information describing the active/selected elements of the receiver coil. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. As an example, for Siemens, coil channels are typically not activated/selected individually, but rather in pre-defined selectable "groups" of individual channels, and the list of the "groups" of elements that are active/selected in any given scan populates the `Coil String` entry in Siemens’ private DICOM fields (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the "active" coil elements. Since individual scans can sometimes not have the intended coil elements selected, it is preferable for this field to be populated directly from the DICOM for each individual scan, so that it can be used as a mechanism for checking that a given scan was collected with the intended coil elements selected |
| CoilString | RECOMMENDED. Information describing the selected element of the receiver coil for channel-level data. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined identifier for individual channels can go in this field. As an example, for Siemens, while coil channels are typically not activated/selected individually, data from individual channels may be reconstructed separately. The DICOM files containing the combined data will have a `Coil String` entry matching the terminology of `ReceiveCoilActiveElements` (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated), while the DICOM files containing channel-level data will have a `Coil String` entry with a unique identifier for the channel (e.g., `H1`-`H32` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the reconstructed channel. |
| GradientSetType | RECOMMENDED. It should be possible to infer the gradient coil from the scanner model. If not, e.g. because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently |
| MRTransmitCoilSequence | RECOMMENDED. This is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence` |
| MatrixCoilMode | RECOMMENDED. (If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (e.g. GRAPPA, SENSE) imaging |
Expand Down Expand Up @@ -114,7 +115,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>][_coil-<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 @@ -175,6 +176,14 @@ sequences using different contrast enhanced images. The label is the name of the
contrast agent. The key `ContrastBolusIngredient` MAY be also be added in the
JSON file, with the same label.

#### The `coil` entity

The OPTIONAL `coil-<label>` key/value can be used to distinguish coil-specific data.
Typically it is used for sequences not employing coil combination (e.g., SWI).
When the file contains data from a single coil, `coil-<label>` SHOULD be provided.
The key `CoilString` MAY also be added in the JSON file, with a corresponding
tsalo marked this conversation as resolved.
Show resolved Hide resolved
identifier for the coil.

Some meta information about the acquisition MAY be provided in an additional
JSON file. See [Common metadata fields](#common-metadata-fields) for a
list of terms and their definitions. There are also some OPTIONAL JSON
Expand Down Expand Up @@ -204,8 +213,8 @@ 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>][_coil-<label>]_<contrast_label>.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_coil-<label>]_sbref.nii[.gz]
```

Imaging data acquired during functional imaging (i.e. imaging which supports
Expand Down Expand Up @@ -249,7 +258,12 @@ reconstruction algorithms (for example ones using motion correction).
See [`fmap` Case 4](01-magnetic-resonance-imaging-data.md#case-4-multiple-phase-encoded-directions-pepolar)
for more information on `dir` field specification.

Multi-echo data MUST be split into one file per echo. Each file shares the same
Similarly the OPTIONAL `coil-<label>` key/value can be used to distinguish
coil-specific data from sequences not employing coil combination.
The key `CoilString` MAY also be added in the JSON file, with a corresponding
coil identifier.

Multi-echo data MUST be split into one file per echo. Each file shares the same
name with the exception of the `_echo-<index>` key/value. For example:

```Text
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 @@ -13,16 +13,17 @@ A general introduction to entities is given in the section on

## Magnetic Resonance Imaging

| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding Modality | Echo | Recording |
|------------------------------------------------------------------------------------------------|---------------|---------------|----------------|---------------|----------------------------|------------------|----------------------------|---------------|--------------------------|----------------|---------------------|
| Format | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>` | `rec-<label>` | `dir-<label>` | `run-<index>` | `mod-<label>` | `echo-<index>` | `recording-<label>` |
| 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 | Coil | Recording |
|------------------------------------------------------------------------------------------------|---------------|---------------|----------------|---------------|----------------------------|------------------|----------------------------|---------------|--------------------------|----------------|----------------|---------------------|
| Format | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>` | `rec-<label>` | `dir-<label>` | `run-<index>` | `mod-<label>` | `echo-<index>` | `coil-<label>` | `recording-<label>` |
| 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 | | | | |
| 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) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | OPTIONAL | |
| func<br>(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
1 change: 1 addition & 0 deletions src/schema/datatypes/anat.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
acq: optional
ce: optional
rec: optional
coil: optional
# Second group
- suffixes:
- defacemask
Expand Down
1 change: 1 addition & 0 deletions src/schema/datatypes/func.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
dir: optional
run: optional
echo: optional
coil: optional
# Second group
- suffixes:
- events
Expand Down
11 changes: 11 additions & 0 deletions src/schema/entities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,17 @@ echo:
Each file shares the same name with the exception of the `_echo-<index>`
key/value.
format: index
coil:
name: Coil
description: |
The `coil-<label>` key/value can be used to distinguish coil-specific data.
Typically it is used for sequences not employing coil combination
(e.g., SWI).
When the file contains data from a single coil, `coil-<label>`
SHOULD be provided.
The key `CoilString` MAY also be added in the JSON file, with a
corresponding identifier for the coil.
format: label
recording:
name: Recording
description: |
Expand Down