Entities
This section compiles the entities (key-value pairs within filenames) described throughout this specification, and describes each.
A general introduction to entities is given in the section on filename structure.
The ordering of entities, and whether each is OPTIONAL, REQUIRED, or MUST NOT be specified for a given file type, is specified 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).
sample
Full name: Sample
Format: sample-<label>
Definition: A sample pertaining to a subject such as tissue, primary cell or cell-free sample.
The sample-<label>
entity is used to distinguish between different samples from the same subject.
The label MUST be unique per subject and is RECOMMENDED to be unique throughout the dataset.
task
Full name: Task
Format: task-<label>
Definition: A set of structured activities performed by the participant. Tasks are usually accompanied by stimuli and responses, and can greatly vary in complexity.
In the context of brain scanning, a task is always tied to one data acquisition. Therefore, even if during one acquisition the subject performed multiple conceptually different behaviors (with different sets of instructions) they will be considered one (combined) task.
While tasks may be repeated across multiple acquisitions, a given task may have different sets of stimuli (for example, randomized order) and participant responses across subjects, sessions, and runs.
The task-<label>
MUST be consistent across subjects and sessions.
Files with the task-<label>
entity SHOULD have an associated
events file,
as well as certain metadata fields in the associated JSON file.
For the purpose of this specification we consider the so-called "resting state" a task,
although events files are not expected for resting state data.
Additionally, a common convention in the specification is to include the word "rest" in
the task
label for resting state files (for example, task-rest
).
tracksys
Full name: Tracking system
Format: tracksys-<label>
Definition: The tracksys-<label>
entity can be used as a key-value pair
to label _motion.tsv and _motion.json files.
It can also be used to label _channel.tsv or _events.tsv files
when they belong to a specific tracking system.
This entity corresponds to the "TrackingSystemName"
metadata field in a *_motion.json file.
tracksys-<label>
entity is a concise string whereas "TrackingSystemName"
may be longer and more human readable.
acq
Full name: Acquisition
Format: acq-<label>
Definition: The acq-<label>
entity 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 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.
The level of detail at which the distinction is made
(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>
entity can be used to distinguish sequences using different contrast enhanced images.
The label is the name of the contrast agent.
This entity represents the "ContrastBolusIngredient"
metadata field.
Therefore, if the ce-<label>
entity is present in a filename,
"ContrastBolusIngredient"
MAY also be added in the JSON file, with the same label.
trc
Full name: Tracer
Format: trc-<label>
Definition: The trc-<label>
entity can be used to distinguish sequences using different tracers.
This entity represents the "TracerName"
metadata field.
Therefore, if the trc-<label>
entity is present in a filename,
"TracerName"
MUST be defined in the associated metadata.
Please note that the <label>
does not need to match the actual value of the field.
stain
Full name: Stain
Format: stain-<label>
Definition: The stain-<label>
key/pair values can be used to distinguish image files
from the same sample using different stains or antibodies for contrast enhancement.
This entity represents the "SampleStaining"
metadata field.
Therefore, if the stain-<label>
entity is present in a filename,
"SampleStaining"
SHOULD be defined in the associated metadata,
although the label may be different.
Descriptions of antibodies SHOULD also be indicated in the "SamplePrimaryAntibodies"
and/or "SampleSecondaryAntibodies"
metadata fields, as appropriate.
rec
Full name: Reconstruction
Format: rec-<label>
Definition: The rec-<label>
entity can be used to distinguish different reconstruction algorithms
(for example, MoCo
for the ones using motion correction).
dir
Full name: Phase-Encoding Direction
Format: dir-<label>
Definition: The dir-<label>
entity can be set to an arbitrary alphanumeric label
(for example, dir-LR
or dir-AP
)
to distinguish different phase-encoding directions.
This entity represents the "PhaseEncodingDirection"
metadata field.
Therefore, if the dir-<label>
entity is present in a filename,
"PhaseEncodingDirection"
MUST be defined in the associated metadata.
Please note that the <label>
does not need to match the actual value of the field.
run
Full name: Run
Format: run-<index>
Definition: The run-<index>
entity is used to distinguish separate data acquisitions with the same acquisition parameters
and (other) entities.
If several data acquisitions (for example, MRI scans or EEG recordings)
with the same acquisition parameters are acquired in the same session,
they MUST be indexed with the run-<index>
entity:
_run-1
, _run-2
, _run-3
, and so on
(only nonnegative integers are allowed as run indices).
If different entities apply,
such as a different session indicated by [ses-<label>
][../appendices/entities.md#ses),
or different acquisition parameters indicated by
acq-<label>
,
then run
is not needed to distinguish the scans and MAY be omitted.
mod
Full name: Corresponding Modality
Format: mod-<label>
Definition: The mod-<label>
entity 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: If files belonging to an entity-linked file collection are acquired at different
echo times, the echo-<index>
entity MUST be used to distinguish individual files.
This entity represents the "EchoTime"
metadata field.
Therefore, if the echo-<index>
entity is present in a filename,
"EchoTime"
MUST be defined in the associated metadata.
Please note that the <index>
denotes the number/index (in the form of a nonnegative integer),
not the "EchoTime"
value of the separate JSON file.
flip
Full name: Flip Angle
Format: flip-<index>
Definition: If files belonging to an entity-linked file collection are acquired at different
flip angles, the _flip-<index>
entity pair MUST be used to distinguish
individual files.
This entity represents the "FlipAngle"
metadata field.
Therefore, if the flip-<index>
entity is present in a filename,
"FlipAngle"
MUST be defined in the associated metadata.
Please note that the <index>
denotes the number/index (in the form of a nonnegative integer),
not the "FlipAngle"
value of the separate JSON file.
inv
Full name: Inversion Time
Format: inv-<index>
Definition: If files belonging to an entity-linked file collection are acquired at different inversion times,
the inv-<index>
entity MUST be used to distinguish individual files.
This entity represents the "InversionTime
metadata field.
Therefore, if the inv-<index>
entity is present in a filename,
"InversionTime"
MUST be defined in the associated metadata.
Please note that the <index>
denotes the number/index (in the form of a nonnegative integer),
not the "InversionTime"
value of the separate JSON file.
mt
Full name: Magnetization Transfer
Format: mt-<label>
Allowed values: on
, off
Definition: If files belonging to an entity-linked file collection are acquired at different
magnetization transfer (MT) states, the _mt-<label>
entity MUST be used to
distinguish individual files.
This entity represents the "MTState"
metadata field.
Therefore, if the mt-<label>
entity is present in a filename,
"MTState"
MUST be defined in the associated metadata.
Allowed label values for this entity are on
and off
,
for images acquired in presence and absence of an MT pulse, respectively.
part
Full name: Part
Format: part-<label>
Allowed values: mag
, phase
, real
, imag
Definition: This entity is used to indicate which component of the complex
representation of the MRI signal is represented in voxel data.
The part-<label>
entity is associated with the DICOM Tag
0008, 9208
.
Allowed label values for this entity are phase
, mag
, real
and imag
,
which are typically used in part-mag
/part-phase
or
part-real
/part-imag
pairs of files.
Phase images MAY be in radians or in arbitrary units.
The sidecar JSON file MUST include the "Units"
of the phase
image.
The possible options are "rad"
or "arbitrary"
.
When there is only a magnitude image of a given type, the part
entity MAY be
omitted.
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 Neuromag/Elekta/MEGIN'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.
hemi
Full name: Hemisphere
Format: hemi-<label>
Allowed values: L
, R
Definition: The hemi-<label>
entity indicates which hemibrain is described by the file.
Allowed label values for this entity are L
and R
, for the left and right
hemibrains, respectively.
space
Full name: Space
Format: space-<label>
Definition: The space-<label>
entity can be used to indicate the way in which electrode positions are interpreted
(for EEG/MEG/iEEG data)
or the spatial reference to which a file has been aligned (for MRI data).
The <label>
MUST be taken from one of the modality specific lists in the
Coordinate Systems Appendix.
For example, for iEEG data, the restricted keywords listed under
iEEG Specific Coordinate Systems
are acceptable for <label>
.
For EEG/MEG/iEEG data, this entity can be applied to raw data, but for other data types, it is restricted to derivative data.
split
Full name: Split
Format: split-<index>
Definition: In the case of long data recordings that exceed a file size of 2Gb,
.fif
, .nwb
, .nix
files are conventionally split into multiple parts.
Each of the .fif
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-Python for .fif
,
which will ensure that not only the filenames, 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.
If there are multiple parts of a recording and the optional scans.tsv
is provided,
all files MUST be listed separately in scans.tsv
and
the entries for the acq_time
column in scans.tsv
MUST all be identical,
as described in Scans file.
recording
Full name: Recording
Format: recording-<label>
Definition: The recording-<label>
entity can be used to distinguish continuous recording files.
This entity is commonly applied when continuous recordings have different sampling frequencies or start times.
For example, physiological recordings with different sampling frequencies may be distinguished using
labels like recording-100Hz
and recording-500Hz
.
chunk
Full name: Chunk
Format: chunk-<index>
Definition: The chunk-<index>
key/value pair is used to distinguish between images of
the same physical sample with different fields of view acquired in the same
imaging experiment.
This entity applies to collections of 2D images, 3D volumes or 4D volume series
(for example, diffusion weighted images), and may be used to indicate different
anatomical structures or regions of the same structure.
seg
Full name: Segmentation
Format: seg-<label>
Definition: The seg-<label>
key/value pair corresponds to a custom label the user
MAY use to distinguish different segmentations.
This entity is only applicable to derivative data.
res
Full name: Resolution
Format: res-<label>
Definition: Resolution of regularly sampled N-dimensional data.
This entity represents the "Resolution"
metadata field.
Therefore, if the res-<label>
entity is present in a filename,
"Resolution"
MUST also be added in the JSON file, to provide interpretation.
This entity is only applicable to derivative data.
den
Full name: Density
Format: den-<label>
Definition: Density of non-parametric surfaces.
This entity represents the "Density"
metadata field.
Therefore, if the den-<label>
entity is present in a filename,
"Density"
MUST also be added in the JSON file, to provide interpretation.
This entity is only applicable to derivative data.
label
Full name: Label
Format: label-<label>
Definition: Tissue-type label, following a prescribed vocabulary. Applies to binary masks and probabilistic/partial volume segmentations that describe a single tissue type.
This entity is only applicable to derivative data.
desc
Full name: Description
Format: desc-<label>
Definition: When necessary to distinguish two files that do not otherwise have a
distinguishing entity, the desc-<label>
entity SHOULD be used.
This entity is only applicable to derivative data.