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 1 commit
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
19 changes: 16 additions & 3 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 @@ -112,7 +112,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>][_ch-<index>]_<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 @@ -171,6 +171,14 @@ JSON file, with the same label.
Similarly the OPTIONAL `rec-<label>` key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).

#### The `ch` entity

The OPTIONAL `ch-<index>` key/value can be used to distinguish channel-specific
data from sequences not employing coil combination.
tsalo marked this conversation as resolved.
Show resolved Hide resolved
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 channel within the coil.
Copy link
Collaborator

Choose a reason for hiding this comment

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

is that really an identifier for the channel or for the coil that channel (currently) is connected? might want to adjust.

FWIW, verified that at least dcm2niix now would dump CoilString entry into the sidecar .json file for SWI file:

$> dcm2niix -b y -z y -o . MR.1.3.12.2.1107.5.2.43.167017.2020011616095414658328735
Chris Rorden's dcm2niiX version v1.0.20190902  (JP2:OpenJPEG) GCC8.3.0 (64-bit Linux)
Found 1 DICOM file(s)
Convert 1 DICOM as ./t_swi_acq-QSMX3echos_20200116145903_23_e3a (264x288x1x1)
Warning: Check that 2D images are not mirrored.
Conversion required 0.022960 seconds (0.022957 for core code).

$> grep Coil t_swi_acq-QSMX3echos_20200116145903_23_e3.json                        
	"ReceiveCoilName": "Head_32",
	"ReceiveCoilActiveElements": "HEA;HEP",
	"CoilString": "H1",

$> grep Siem t_swi_acq-QSMX3echos_20200116145903_23_e3.json
	"Manufacturer": "Siemens",
	"PulseSequenceDetails": "%SiemensSeq%_gre",

Copy link
Member Author

Choose a reason for hiding this comment

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

Honestly, I'm not familiar enough with the hardware to know if it's referring to the channel or the individual coil. All I can tell is that it's not referring to an array of coils like ReceiveCoilActiveElements.

If `ch-<index>` is not used, data are assumed to be combined across channels.
Copy link
Collaborator

Choose a reason for hiding this comment

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

I would remove this statement. If you grep for "assume" you will see that it is not common to state assumptions in BIDS. Moreover, I could have individual channels and combined data.

Copy link
Member Author

Choose a reason for hiding this comment

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

In the current proposal, they say "if skipped total is assumed", so my thinking was that having both channel-wise and combined data would look like:

func/
    sub-XXX_task-YYY_bold.nii.gz  # combined
    sub-XXX_task-YYY_ch-01_bold.nii.gz
    ...
    sub-XXX_task-YYY_ch-32_bold.nii.gz

First, do you think it makes sense to mix having the entity and not within the same run like that or should the specification allow key/value pairs with an index OR a label (specifically, "combined")?

Second, would a better way of saying that there's a default be like the following (from the run entity description):

When there is only one scan of a given type the run key MAY be omitted.

So maybe:

When only combined data are reconstructed the channel key MAY be omitted.

Copy link
Collaborator

Choose a reason for hiding this comment

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

First, do you think it makes sense to mix having the entity and not within the same run like that or should the specification allow key/value pairs with an index OR a label (specifically, "combined")?

IMHO it is ok.

Second, would a better way of saying that there's a default be like the following (from the run entity description):

When there is only one scan of a given type the run key MAY be omitted.

So maybe:

When only combined data are reconstructed the channel key MAY be omitted.

run is a bit of a different beast IMHO to make direct analogy here. The suggested phrase sounds a bit off to me, since if data (in the file) is combined, there can be no channel. Overall, I would not overdo it -- the purpose of all those suffixes is to provide high level information about the file and to disambiguate from one file to another. So, may be we could flip it to

When file contains data from a single channel, ch-<index> SHOULD be provided

Then, in the case when "combined" data is actually combined from a single channel recording (is that within even 0.1% of cases? ;)), it would be up to a user to decide to include or not the ch key. If they have multiple channels, the need for using _ch becomes obvious -- to disambiguate.

Copy link
Member Author

Choose a reason for hiding this comment

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

Thank you! I've incorporated your suggestions.

Copy link

Choose a reason for hiding this comment

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

I am not sure whether it is the right place to post, but I would like to warn about confusing channel and coil. As we have just discussed with @tsalo on mattermost, channels refer to the two parts of the quadrature used by coils (see: http://mriquestions.com/real-v-imaginary.html) resulting in real and imaginary (or magnitude and phase) data.
Therefore, I suggest using coil rather than ch(annel) to refer to coils.

Copy link
Member Author

Choose a reason for hiding this comment

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

I've switched from ch to coil. Thank you for the insight @tiborauer.

Copy link
Collaborator

Choose a reason for hiding this comment

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

@tiborauer do you have example of such data? wouldn't you have then 2 _ch- files - one representing I and another Q? sure thing then someone could transform them into "magnitude" and "phase" images, making it needing some _coil or another entity to represent "combination" of data from different channels? (so may be we need both _ch and _coil?)

Copy link

@tiborauer tiborauer Aug 25, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

@yarikoptic, I am afraid I do not work with raw data (in MRI physics POV), but any data could be saved as such.
I agree with you that channels refer to the two parts: real and imaginary (see the link in my previous comment), which can be transformed into magnitude and phase; which means that entity part (referring to magnitude and phase and also part of BEP001) and ch (referring to real and imaginary) are different. Entity coil, however, should correspond to another level, namely the transmitter/receiver hardware usually containing multiple coil elements. See http://mriquestions.com/array-coils.html explaining Coil Elements > Segments > Channels; so you may need even more entities. :)
(N.B. You may also want to differentiate between transmitter and receiver coils because different coils can be used for excitation and reception.)

Copy link
Member Author

Choose a reason for hiding this comment

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

As proposed in #508 (and #424 now), part supports both phase/magnitude and real/imaginary, so I'm not sure if that's still a concern.

I'm quite comfortable ignoring transmitter coils. I think it falls sufficiently outside the 80% BIDS is meant to cover. If someone is going to collect different runs with different transmitter coils, they can use acq to differentiate the files, I think.

Copy link

@tiborauer tiborauer Sep 1, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

If you are happy with using the same entity part for phase/magnitude and real/imaginary, then it is fine. They are somewhat redundant anyway because one can compute one pair from the other pair. However, we have to be explicit about these - mutually exclusive - representations.

Distinguishing coils and channels is still a concern.

I agree with ignoring the transmitter/receiver coils. In most cases, the same coil(set) is used for both.


If the structural images included in the dataset were defaced (to protect
identity of participants) one CAN provide the binary mask that was used to
remove facial features in the form of `_defacemask` files. In such cases the
Expand Down Expand Up @@ -202,8 +210,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>][_ch-<index>]_<contrast_label>.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_ch-<index>]_sbref.nii[.gz]
```

Imaging data acquired during functional imaging (i.e. imaging which supports
Expand Down Expand Up @@ -247,6 +255,11 @@ 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.

Similarly the OPTIONAL `ch-<index>` key/value can be used to distinguish
channel-specific data from sequences not employing coil combination.
The key CoilString MAY also be added in the JSON file, with a corresponding
channel 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:

Expand Down
40 changes: 20 additions & 20 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 @@ -10,23 +10,23 @@ file type are denoted. Entity formats indicate whether the value is alphanumeric
A general introduction to entities is given in the section on
[file name structure](../02-common-principles.md#file-name-structure)

| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding modality | Echo | Recording | Processed (on device) | Space |
| :--------------------------------------------------------------------------------------------- | :------------ | :------------ | :------------- | :------------ | :----------------------- | :------------- | :----------------------- | :------------ | :--------------------- | :------------- | :------------------ | :-------------------- | :---------------|
| Format | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>` | `rec-<label>` | `dir-<label>` | `run-<index>` | `mod-<label>` | `echo-<index>` | `recording-<label>` | `proc-<label>` | `space-<label>` |
| anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | | | | | | |
| anat<br>(defacemask) | REQUIRED | OPTIONAL | | OPTIONAL | OPTIONAL | OPTIONAL | | | 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 | OPTIONAL | |
| dwi<br>(dwi bvec bval) | 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 | | | | | |
| beh<br>(events stim physio) | REQUIRED | OPTIONAL | REQUIRED | | | | | | | | | | |
| meg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | OPTIONAL | |
| eeg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | | |
| ieeg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | | |
| channels<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | REQUIRED | | | | | OPTIONAL | | | | | |
| headshape<br>(meg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | OPTIONAL |
| markers<br>(meg) | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | | | | | | | | | OPTIONAL |
| photo<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | |
| electrodes<br>(eeg/ieeg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | OPTIONAL |
| events<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | REQUIRED | | | | | OPTIONAL | | | | | |
| Entity | Subject | Session | Task | Acquisition | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run | Corresponding modality | Echo | Channel | Recording | Processed (on device) | Space |
| :--------------------------------------------------------------------------------------------- | :------------ | :------------ | :------------- | :------------ | :----------------------- | :------------- | :----------------------- | :------------ | :--------------------- | :------------- | :----------- | :------------------ | :-------------------- | :---------------|
| Format | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>` | `rec-<label>` | `dir-<label>` | `run-<index>` | `mod-<label>` | `echo-<index>` | `ch-<index>` | `recording-<label>` | `proc-<label>` | `space-<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 | | | | | |
| func<br>(bold cbv phase sbref events) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | OPTIONAL | | | |
| func<br>(physio stim) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | OPTIONAL | | OPTIONAL | | | | OPTIONAL | OPTIONAL | |
| dwi<br>(dwi bvec bval) | 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 | | | | | | |
| beh<br>(events stim physio) | REQUIRED | OPTIONAL | REQUIRED | | | | | | | | | | | |
| meg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | | OPTIONAL | |
| eeg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | | | |
| ieeg<br> | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | | | | OPTIONAL | | | | | | |
| channels<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | REQUIRED | | | | | OPTIONAL | | | | | | |
| headshape<br>(meg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | | OPTIONAL |
| markers<br>(meg) | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | | | | | | | | | | OPTIONAL |
| photo<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | | |
| electrodes<br>(eeg/ieeg) | REQUIRED | OPTIONAL | | OPTIONAL | | | | | | | | | | OPTIONAL |
| events<br>(meg/eeg/ieeg) | REQUIRED | OPTIONAL | REQUIRED | | | | | OPTIONAL | | | | | | |