Appendix IX: Entities
This section compiles the entities (key-value pairs) described throughout this specification, and describes each.
A general introduction to entities is given in the section on file name structure.
The ordering of entities and whether it is allowed, OPTIONAL, or REQUIRED for each is given in the Entity Table.
sub
Full name: Subject
Format: sub-<label>
Definition: A person or animal participating in the study.
ses
Full name: Session
Format: ses-<label>
Definition: A logical grouping of neuroimaging and behavioral data consistent across subjects. Session can (but doesn't have to) be synonymous to a visit in a longitudinal study. In general, subjects will stay in the scanner during one session. However, for example, if a subject has to leave the scanner room and then be re-positioned on the scanner bed, the set of MRI acquisitions will still be considered as a session and match sessions acquired in other subjects. Similarly, in situations where different data types are obtained over several visits (for example fMRI on one day followed by DWI the day after) those can be grouped in one session. Defining multiple sessions is appropriate when several identical or similar data acquisitions are planned and performed on all -or most- subjects, often in the case of some intervention between sessions (for example, training).
task
Full name: Task
Format: task-<label>
Definition: Each task has a unique label that MUST only consist of letters and/or numbers (other characters, including spaces and underscores, are not allowed). Those labels MUST be consistent across subjects and sessions.
acq
Full name: Acquisition
Format: acq-<label>
Definition: The acq-<label>
key/value pair corresponds to a custom label the
user 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
resolution.
In such case two files could have the following names:
sub-01_acq-highres_T1w.nii.gz
and sub-01_acq-lowres_T1w.nii.gz
, however
the user is free to choose any other label than highres and lowres as long
as they are consistent across subjects and sessions.
In case different sequences are used to record the same modality (for example, RARE
and FLASH for T1w) this field can also be used to make that distinction.
At what level of detail to make the distinction (for example, just between RARE and
FLASH, or between RARE, FLASH, and FLASHsubsampled) remains at the
discretion of the researcher.
ce
Full name: Contrast Enhancing Agent
Format: ce-<label>
Definition: The 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.
rec
Full name: Reconstruction
Format: rec-<label>
Definition: The rec-<label>
key/value can be used to distinguish
different reconstruction algorithms (for example ones using motion
correction).
dir
Full name: Phase-Encoding Direction
Format: dir-<label>
Definition: The dir-<label>
key/value can be used to distinguish
different phase-encoding directions.
run
Full name: Run
Format: run-<index>
Definition: If several scans of the same modality are acquired they MUST be indexed
with a key-value pair: _run-1
, _run-2
, ..., _run-<index>
(only nonnegative integers are allowed for the <index>
).
When there is only one scan of a given type the run key MAY be omitted.
mod
Full name: Corresponding Modality
Format: mod-<label>
Definition: The mod-<label>
key/value pair corresponds to modality label for defacing
masks, for example, T1w, inplaneT1, referenced by a defacemask image.
For example, sub-01_mod-T1w_defacemask.nii.gz
.
echo
Full name: Echo
Format: echo-<index>
Definition: 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.
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.
recording
Full name: Recording
Format: recording-<label>
Definition: More than one continuous recording file can be included (with different
sampling frequencies).
In such case use different labels.
For example: _recording-contrast
, _recording-saturation
.
proc
Full name: Processed (on device)
Format: proc-<label>
Definition: The proc label is analogous to rec for MR and denotes a variant of a file that was a result of particular processing performed on the device. This is useful for files produced in particular by Elekta’s MaxFilter (for example, sss, tsss, trans, quat or mc), which some installations impose to be run on raw data because of active shielding software corrections before the MEG data can actually be exploited.
space
Full name: Space
Format: space-<label>
Definition: The space label (*[_space-<label>]_electrodes.tsv
) can be used
to indicate the way in which electrode positions are interpreted.
The space label needs to be taken from the list in Appendix VIII.
split
Full name: Split
Format: split-<index>
Definition: In the case of long data recordings that exceed a file size of 2Gb, the .fif files are conventionally split into multiple parts. Each of these files has an internal pointer to the next file. This is important when renaming these split recordings to the BIDS convention.
Instead of a simple renaming, files should be read in and saved under their
new names with dedicated tools like MNE, which will ensure that not only
the file names, but also the internal file pointers will be updated.
It is RECOMMENDED that .fif files with multiple parts use the
split-<index>
entity to indicate each part.