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 2 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
37 changes: 34 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>][_part-<mag|phase>][_run-<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,16 @@ 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 `part` entity

Complex-valued data MUST be split into one file for each data type.
Each file shares the same name with the exception of the `part-<mag|phase>`
key/value.

In cases where both magnitude and phase data are not reconstructed, the
`part-<mag|phase>` key/value is OPTIONAL.
If the key/value is not provided, data are assumed to be magnitude.

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 +212,10 @@ 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>]_bold.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>]_phase.nii[.gz]
tsalo marked this conversation as resolved.
Show resolved Hide resolved
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<mag|phase>]_cbv.nii[.gz]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_ce-<label>][_dir-<label>][_rec-<label>][_run-<index>][_echo-<index>][_part-<mag|phase>]_sbref.nii[.gz]
Copy link
Collaborator

Choose a reason for hiding this comment

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

I am not sure if such detailed specification and expansion of different contrast_labels is needed here.
_bold is indeed a special case though since now it has a dedicated _phase. So now there cannot be another func contrast than _bold which would have its _phase.
NB ASL BEP005 seems decided to avoid func/ and went for a dedicted perf/ (perfusion) although its purpose AFAIK would be func/.
Unfortunately I did not follow the discussion in #128. I would have voted for any contrast_label to "assume" its default "composition" - either it is a mag or phase or combined if no _part is provided. Then #128 could have resulted in adding _part-phase and having explicit _part-phase_bold, opening possibilities for any other _part-phase_<contrast>.

Sure thing _part- makes no sense with _phase, but I think that is just a corner case which might be gone in 2.0.
So why not just to keep [_part-<mag|phase>]_<contrast_label> and just add a note to _phase in the table that _part then should not be specified. Also it might be worth starting adding "deprecation" statements on elements which will be removed in 2.0, but that would be a separate issue I guess ;)

```

Imaging data acquired during functional imaging (i.e. imaging which supports
Expand Down Expand Up @@ -265,6 +277,25 @@ Please note that the `<index>` denotes the number/index (in a form of an
integer) of the echo not the echo time value which needs to be stored in the
field EchoTime of the separate JSON file.

Complex-valued data MUST be split into one file for each data type.
For BOLD data, there are separate suffices for magnitude (`_bold`) and phase
(`_phase`) data.
tsalo marked this conversation as resolved.
Show resolved Hide resolved
For other contrasts (e.g., `_sbref` or `_cbv`), each file shares the same
name with the exception of the `part-<mag|phase>` key/value. For example:

```Text
sub-01/
func/
sub-01_task-cuedSGT_bold.nii.gz
sub-01_task-cuedSGT_bold.json
sub-01_task-cuedSGT_phase.nii.gz
sub-01_task-cuedSGT_phase.json
sub-01_task-cuedSGT_part-mag_sbref.nii.gz
sub-01_task-cuedSGT_part-mag_sbref.nii.gz
sub-01_task-cuedSGT_part-phase_sbref.nii.gz
sub-01_task-cuedSGT_part-phase_sbref.nii.gz
tsalo marked this conversation as resolved.
Show resolved Hide resolved
```

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

Expand Down
1 change: 1 addition & 0 deletions src/99-appendices/01-contributors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ your name is not listed, please add it.
- Nick F. Ramsey 📖
- Alex Rockhill 📖🔧
- Ariel Rokem 📖
- Taylor Salo 📖💬
- Matt Sanderson 📖💻
- Gunnar Schaefer 📖
- Jan-Mathijs Schoffelen 📖
Expand Down
41 changes: 21 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,24 @@ 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 | Recording | Part | 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>` | `part-<mag|phase>` | `proc-<label>` | `space-<label>` |
tsalo marked this conversation as resolved.
Show resolved Hide resolved
| 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 phase) | REQUIRED | OPTIONAL | REQUIRED | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL | | OPTIONAL | | | | |
| func<br>(cbv 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 | | | | 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 | | | | | | |