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

Jump to bottom

[FIX] harmonize and thus shorten templates etc #93

Merged
merged 14 commits into from
Nov 28, 2018
Merged

[FIX] harmonize and thus shorten templates etc #93

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
375c040
RF: use lowercase optional instead of OPTIONAL
yarikoptic Nov 20, 2018
1c4b19a
[DATALAD RUNCMD] No need for session_ prefix in ses-<session_label> -…
yarikoptic Nov 20, 2018
611a1a8
[DATALAD RUNCMD] No need for participant_ prefix in sub-<participant_…
yarikoptic Nov 20, 2018
e5538b9
[DATALAD RUNCMD] No need for task_ prefix in task-<task_label> -- imp…
yarikoptic Nov 20, 2018
6b32ef1
[DATALAD RUNCMD] No need for run_ prefix in run-<run_index> -- implied
yarikoptic Nov 20, 2018
568bf6d
[DATALAD RUNCMD] No need for dir_ prefix in dir-<dir_label> -- implied
yarikoptic Nov 20, 2018
4d42623
ENH: adjusting the text since there is no longer dir_label
yarikoptic Nov 20, 2018
4f71449
Merge remote-tracking branch 'origin/master' into rf-harmonize
yarikoptic Nov 25, 2018
50f1735
Revert "RF: use lowercase optional instead of OPTIONAL"
yarikoptic Nov 27, 2018
d4de435
Consistent use of OPTIONAL (not optional or (optional)) keyword in MR…
yarikoptic Nov 27, 2018
c961824
Consistent use of OPTIONAL and REQUIRED (instead of lower etc case) i…
yarikoptic Nov 27, 2018
d5c628d
One more OPTIONAL instead of (optional)
yarikoptic Nov 27, 2018
9221149
BF: fixed table formatting
yarikoptic Nov 27, 2018
0aa1ab3
Merge remote-tracking branch 'origin/master' into rf-harmonize
yarikoptic Nov 28, 2018
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
8 changes: 4 additions & 4 deletions src/03-modality-agnostic-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Optional: Yes

The purpose of this file is to describe properties of participants such as age,
handedness, sex, etc. In case of single session studies this file has one
compulsory column `participant_id` that consists of `sub-<participant_label>`,
compulsory column `participant_id` that consists of `sub-<label>`,
followed by a list of optional columns describing participants. Each participant
needs to be described by one and only one row.

Expand All @@ -102,7 +102,7 @@ example responses from multiple questionnaires) they can be split into
individual files separate from `participants.tsv`. Those measurements should be
kept in phenotype/ folder and end with the `.tsv` extension. They can include
arbitrary set of columns, but one of them has to be participant_id with matching
`sub-<participant_label>`. As with all other tabular data, those additional
`sub-<label>`. As with all other tabular data, those additional
phenotypic information files can be accompanied by a JSON file describing the
columns in detail (see [here](02-common-principles.md#tabular-files)).
In addition to the column description, a
Expand Down Expand Up @@ -152,8 +152,8 @@ questionnaire).
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<participant_label>[_ses-<session_label>]_scans.tsv
sub-<label>/[ses-<label>/]
sub-<label>[_ses-<label>]_scans.tsv
```

Optional: Yes
Expand Down
86 changes: 43 additions & 43 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 @@ -110,10 +110,10 @@ whenever possible.
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
anat/
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>]_<modality_label>.nii[.gz]
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_ce-<label>][_rec-<label>][_run-<index>][_mod-<label>]_defacemask.nii[.gz]
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>][_mod-<label>]_defacemask.nii[.gz]
```

Anatomical (structural) data acquired for that participant. Currently supported
Expand Down Expand Up @@ -142,7 +142,7 @@ run labels). When there is only one scan of a given type the run key MAY be
omitted. Please note that diffusion imaging data is stored elsewhere (see
below).

The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label the user
The optional `acq-<label>` key/value pair corresponds to a custom label the user
Copy link
Contributor

Choose a reason for hiding this comment

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

Any reason why lowercase OPTIONAL? It's supposed to be an indication that this is a RFC2119 label. If you are proposing to change that it should be done in another PR.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

ha, also found https://tools.ietf.org/html/rfc8174 ;-) so indeed then should be all UPPERCASE to be keywords.
Again -- I was just aiming for consistency and there were uses both ways, I will just push (later today) a fix to get them all UPPERCASED

MAY use to distinguish a different set of parameters used for acquiring the same
modality. For example this should be used when a study includes two T1w images -
one full brain low resolution and and one restricted field of view but high
Expand All @@ -155,12 +155,12 @@ can also be used to make that distinction. At what level of detail to make the
distinction (e.g. just between RARE and FLASH, or between RARE, FLASH, and
FLASHsubsampled) remains at the discretion of the researcher.

Similarly the OPTIONAL `ce-<label>` key/value can be used to distinguish
Similarly the optional `ce-<label>` key/value can be used to distinguish
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.

Similarly the OPTIONAL `rec-<label>` key/value can be used to distinguish
Similarly the optional `rec-<label>` key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).

If the structural images included in the dataset were defaced (to protect
Expand Down Expand Up @@ -191,10 +191,10 @@ Currently supported image contrasts include:
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
func/
sub-<participant_label>[_ses-<session_label>]_task-<task_label>[_acq-<label>][_ce-<label>][_dir-<dir_label>][_rec-<label>][_run-<index>][_echo-<index>]_<contrast_label>.nii[.gz]
sub-<participant_label>[_ses-<session_label>]_task-<task_label>[_acq-<label>][_ce-<label>][_dir-<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>]_<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]
```

Imaging data acquired during functional imaging (i.e. imaging which supports
Expand All @@ -215,7 +215,7 @@ If more than one run of the same task has been acquired a key/value pair:
defined as the same task, but in some cases it can mean different set of stimuli
(for example randomized order) and participant responses.

The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label one may
The optional `acq-<label>` key/value pair corresponds to a custom label one may
use to distinguish different set of parameters used for acquiring the same task.
For example this should be used when a study includes two resting state images -
one single band and one multiband. In such case two files could have the
Expand All @@ -224,15 +224,15 @@ following names: `sub-01_task-rest_acq-singleband_bold.nii.gz` and
other label than `singleband` and `multiband` as long as they are consistent
across subjects and sessions and consist only of the legal label characters.

Similarly the OPTIONAL `ce-<label>` key/value can be used to distinguish
Similarly the optional `ce-<label>` key/value can be used to distinguish
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.

Similarly the optional `rec-<label>` key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion correction).

Similarly the optional `dir-<dir_label>` and `rec-<label>` key/values
Similarly the optional `dir-<label>` and `rec-<label>` key/values
can be used to distinguish different phase-encoding directions and
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)
Expand Down Expand Up @@ -321,10 +321,10 @@ sub-control01/
```

If this information is the same for all participants, sessions and runs it can
be provided in `task-<task_label>_bold.json` (in the root directory of the
be provided in `task-<label>_bold.json` (in the root directory of the
dataset). However, if the information differs between subjects/runs it can be
specified in the
`sub-<participant_label>/func/sub-<participant_label>_task-<task_label>[_acq-<label>][_run-<index>]_bold.json` file.
`sub-<label>/func/sub-<label>_task-<label>[_acq-<label>][_run-<index>]_bold.json` file.
If both files are specified fields from the file corresponding to a particular
participant, task and run takes precedence.

Expand All @@ -333,14 +333,14 @@ participant, task and run takes precedence.
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
dwi/
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_dwi.nii[.gz]
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_dwi.bval
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_dwi.bvec
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_dwi.json
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_sbref.nii[.gz]
sub-<participant_label>[_ses-<session_label>][_acq-<label>][_dir-<dir_label>][_run-<index>]_sbref.json
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
```

Diffusion-weighted imaging data acquired for that participant. The optional
Expand Down Expand Up @@ -439,26 +439,26 @@ the user may use to distinguish different set of parameters.
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phasediff.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phasediff.json
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_magnitude1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phasediff.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
```

(optional)

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_magnitude2.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
```

This is a common output for build in fieldmap sequence on Siemens scanners. In
this particular case the sidecar JSON file has to define the Echo Times of the
two phase images used to create the difference image. `EchoTime1` corresponds to
the shorter echo time and `EchoTime2` to the longer echo time. Similarly
`_magnitude1` image corresponds to the shorter echo time and the OPTIONAL
`_magnitude1` image corresponds to the shorter echo time and the optional
`_magnitude2` image to the longer echo time. For example:

```JSON
Expand All @@ -474,14 +474,14 @@ the shorter echo time and `EchoTime2` to the longer echo time. Similarly
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phase1.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phase1.json
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phase2.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_phase2.json
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_magnitude1.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_magnitude2.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase1.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_phase2.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude1.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude2.nii[.gz]
```

Similar to the case above, but instead of a precomputed phase difference map two
Expand All @@ -500,11 +500,11 @@ corresponding `EchoTime` values. For example:
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_magnitude.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_fieldmap.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_run-<run_index>]_fieldmap.json
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_magnitude.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_run-<index>]_fieldmap.json
```

In some cases (for example GE) the scanner software will output a precomputed
Expand All @@ -524,10 +524,10 @@ the fieldmap. The possible options are: `Hz`, `rad/s`, or `Tesla`. For example:
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
fmap/
sub-<label>[_ses-<session_label>][_acq-<label>][_ce-<label>]_dir-<dir_label>[_run-<run_index>]_epi.nii[.gz]
sub-<label>[_ses-<session_label>][_acq-<label>][_ce-<label>]_dir-<dir_label>[_run-<run_index>]_epi.json
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.nii[.gz]
sub-<label>[_ses-<label>][_acq-<label>][_ce-<label>]_dir-<label>[_run-<index>]_epi.json
```

The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
Expand All @@ -550,7 +550,7 @@ example
}
```

`dir_label` value can be set to arbitrary alphanumeric label (`[a-zA-Z0-9]+` for
`label` value of `_dir-` can be set to arbitrary alphanumeric label (`[a-zA-Z0-9]+` for
example `LR` or `AP`) that can help users to distinguish between different
files, but should not be used to infer any scanning parameters (such as phase
encoding directions) of the corresponding sequence. Please rely only on the JSON
Expand Down
22 changes: 11 additions & 11 deletions src/04-modality-specific-files/02-magnetoencephalography.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ academic literature:
Template:

```Text
sub-<participant_label>/
sub-<label>/
[ses-<label>]/
meg/
sub-<participant_label>[_ses-<label>]_task-<task_label>[_acq-<label>][_run-<index>][_proc-<label>]_meg.<manufacturer_specific_extension>
[sub-<participant_label>[_ses-<label>]_task-<task_label>[_acq-<label>][_run-<index>][_proc-<label>]_meg.json]
sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>]_meg.<manufacturer_specific_extension>
[sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>]_meg.json]
```

Unprocessed MEG data MUST be stored in the native file format of the MEG
Expand Down Expand Up @@ -177,10 +177,10 @@ on local REB/IRB ethics board policy.
Template:

```Text
sub-<participant_label>/
sub-<label>/
[ses-<label>]/
meg/
[sub-<participant_label>[_ses-<label>]_task-<task_label>[_acq-<label>][_run-<index>][_proc-<label>]_channels.tsv]
[sub-<label>[_ses-<label>]_task-<label>[_acq-<label>][_run-<index>][_proc-<label>]_channels.tsv]
```

This file is RECOMMENDED as it provides easily searchable information across
Expand Down Expand Up @@ -272,10 +272,10 @@ UADC001 AUDIO V envelope of audio signal presented to participant
Template:

```Text
sub-<participant_label>/
sub-<label>/
[ses-<label>]/
meg/
[sub-<participant_label>[_ses-<label>][_acq-<label>]_coordsystem.json]
[sub-<label>[_ses-<label>][_acq-<label>]_coordsystem.json]
```

OPTIONAL. A JSON document specifying the coordinate system(s) used for the MEG,
Expand Down Expand Up @@ -362,10 +362,10 @@ Photos of the anatomical landmarks and/or head localization coils
Template:

```Text
sub-<participant_label>/
sub-<label>/
[ses-<label>]/
meg/
[sub-<participant_label>[_ses-<label>][_acq-<label>]_photo.jpg]
[sub-<label>[_ses-<label>][_acq-<label>]_photo.jpg]
```

Photos of the anatomical landmarks and/or head localization coils on the
Expand All @@ -385,10 +385,10 @@ actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg`
Template:

```Text
sub-<participant_label>/
sub-<label>/
[ses-<label>]/
meg/
[sub-<participant_label>[_ses-<label>][_acq-<label>]_headshape.<manufacturer_specific_extension>]
[sub-<label>[_ses-<label>][_acq-<label>]_headshape.<manufacturer_specific_extension>]
```

This file is RECOMMENDED.
Expand Down
2 changes: 1 addition & 1 deletion src/04-modality-specific-files/03-task-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Template:

```Text
sub-<participant_label>/[ses-<session_label>]
sub-<label>/[ses-<label>]
func/
<matches>_events.tsv
<matches>_events.json
Expand Down
2 changes: 1 addition & 1 deletion src/04-modality-specific-files/04-physiological-and-other-continous-recordings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
func/
<matches>[_recording-<label>]_physio.tsv.gz
<matches>[_recording-<label>]_physio.json
Expand Down
18 changes: 9 additions & 9 deletions src/04-modality-specific-files/05-behavioural-experiments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@
Template:

```Text
sub-<participant_label>/[ses-<session_label>/]
sub-<label>/[ses-<label>/]
beh/
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_events.tsv
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_events.json
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_beh.tsv
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_beh.json
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_physio.tsv.gz
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_physio.json
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_stim.tsv.gz
sub-<participant_label>[_ses-<session_label>]_task-<task_name>_stim.json
sub-<label>[_ses-<label>]_task-<task_name>_events.tsv
sub-<label>[_ses-<label>]_task-<task_name>_events.json
sub-<label>[_ses-<label>]_task-<task_name>_beh.tsv
sub-<label>[_ses-<label>]_task-<task_name>_beh.json
sub-<label>[_ses-<label>]_task-<task_name>_physio.tsv.gz
sub-<label>[_ses-<label>]_task-<task_name>_physio.json
sub-<label>[_ses-<label>]_task-<task_name>_stim.tsv.gz
sub-<label>[_ses-<label>]_task-<task_name>_stim.json
```

In addition to logs from behavioral experiments performed along imaging data
Expand Down
12 changes: 6 additions & 6 deletions src/05-longitudinal-and-multi-site-studies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Longitudinal studies with multiple sessions (visits)

Multiple sessions (visits) are encoded by adding an extra layer of directories
and file names in the form of `ses-<session_label>`. Session label can consist
and file names in the form of `ses-<label>`. Session label can consist
only of alphanumeric characters `[a-zA-Z0-9]` and should be consistent across
subjects. If numbers are used in session labels we recommend using zero padding
(for example `ses-01`, `ses-11` instead of `ses-1`, `ses-11`). This makes
results of alphabetical sorting more intuitive. Acquisition time of session can
be defined in the sessions file (see below for details).

The extra session layer (at least one `/ses-<session_label>` subfolder) should
The extra session layer (at least one `/ses-<label>` subfolder) should
be added for all subjects if at least one subject in the dataset has more than
one session. Skipping the session layer for only some subjects in the dataset is
not allowed. If a `/ses-<session_label>` subfolder is included as part of the
directory hierarchy, then the same `ses-<session_label>` tag must also be
not allowed. If a `/ses-<label>` subfolder is included as part of the
directory hierarchy, then the same `ses-<label>` tag must also be
included as part of the file names themselves.

```Text
Expand Down Expand Up @@ -64,8 +64,8 @@ CHANGES
Template:

```Text
sub-<participant_label>/
sub-<participant_label>_sessions.tsv
sub-<label>/
sub-<label>_sessions.tsv
```

Optional: Yes
Expand Down
Loading