---
subject:
  name: Subject
  entity: sub
  description: |
    A person or animal participating in the study.
  format: label
session:
  name: Session
  entity: ses
  description: |
    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).
  format: label
task:
  name: Task
  entity: task
  format: label
  description: |
    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.
acquisition:
  name: Acquisition
  entity: acq
  description: |
    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.
  format: label
ceagent:
  name: Contrast Enhancing Agent
  entity: ce
  description: |
    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 also be added in the JSON file,
    with the same label.
  format: label
tracer:
  name: Tracer
  entity: trc
  description: |
    The `trc-<label>` key/value can be used to distinguish
    sequences using different tracers.
    The key `TracerName` MUST also be included in the associated JSON file,
    although the label may be different.
  format: label
reconstruction:
  name: Reconstruction
  entity: rec
  description: |
    The `rec-<label>` key/value can be used to distinguish
    different reconstruction algorithms (for example ones using motion
    correction).
  format: label
direction:
  name: Phase-Encoding Direction
  entity: dir
  description: |
    The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
    (for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
    directions.
  format: label
run:
  name: Run
  entity: run
  description: |
    If several scans with the same acquisition parameters are acquired in the same session,
    they MUST be indexed with the [`run-<index>`](../99-appendices/09-entities.md#run) entity:
    `_run-1`, `_run-2`, `_run-3`, and so on (only nonnegative integers are allowed as
    run labels).

    If different entities apply,
    such as a different session indicated by [`ses-<label>`](../99-appendices/09-entities.md#ses),
    or different acquisition parameters indicated by
    [`acq-<label>`](../99-appendices/09-entities.md#acq),
    then `run` is not needed to distinguish the scans and MAY be omitted.
  format: index
modality:
  name: Corresponding Modality
  entity: mod
  description: |
    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`.
  format: label
echo:
  name: Echo
  entity: echo
  description: |
    If files belonging to an entity-linked file collection are acquired at different
    echo times, the `_echo-<index>` key/value pair MUST be used to distinguish
    individual files.
    This entity represents the `EchoTime` metadata field. Please note that the `<index>`
    denotes the number/index (in the form of a nonnegative integer), not the
    `EchoTime` value which needs to be stored in the field `EchoTime` of the separate
    JSON file.
  format: index
flip:
  name: Flip Angle
  entity: flip
  description: |
    If files belonging to an entity-linked file collection are acquired at different
    flip angles, the `_flip-<index>` key/value pair MUST be used to distinguish
    individual files.
    This entity represents the `FlipAngle` metadata field. Please note that the `<index>`
    denotes the number/index (in the form of a nonnegative integer), not the `FlipAngle`
    value which needs to be stored in the field `FlipAngle` of the separate JSON file.
  format: index
inversion:
  name: Inversion Time
  entity: inv
  description: |
    If files belonging to an entity-linked file collection are acquired at different
    inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
    individual files.
    This entity represents the `InversionTime` metadata field. Please note that the `<index>`
    denotes the number/index (in the form of a nonnegative integer), not the `InversionTime`
    value which needs to be stored in the field `InversionTime` of the separate JSON file.
  format: index
mtransfer:
  name: Magnetization Transfer
  entity: mt
  description: |
    If files belonging to an entity-linked file collection are acquired at different
    magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
    distinguish individual files.
    This entity represents the `MTState` metadata field. Allowed label values for this
    entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
    respectively.
  format: label
part:
  name: Part
  entity: part
  description: |
    This entity is used to indicate which component of the complex
    representation of the MRI signal is represented in voxel data.
    The `part-<label>` key/value pair 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` key MAY be
    omitted.
  format: label
recording:
  name: Recording
  entity: recording
  description: |
    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`.
  format: label
processing:
  name: Processed (on device)
  entity: proc
  description: |
    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.
  format: label
space:
  name: Space
  entity: space
  description: |
    The space 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 space `<label>` MUST be taken from one of the modality specific lists in
    [Appendix VIII](../99-appendices/08-coordinate-systems.md).
    For example for iEEG data, the restricted keywords listed under
    [iEEG Specific Coordinate Systems](../99-appendices/08-coordinate-systems.md#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.
  format: label
split:
  name: Split
  entity: split
  description: |
    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-Python](https://mne.tools/),
    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.
    If there are multiple parts of a recording and the optional `scans.tsv` is provided,
    remember to list all files separately in `scans.tsv` and that the entries for the
    `acq_time` column in `scans.tsv` MUST all be identical, as described in
    [Scans file](../03-modality-agnostic-files.md#scans-file).
  format: index
resolution:
  name: Resolution
  entity: res
  description: |
    Resolution of regularly sampled N-dimensional data.
    MUST have a corresponding `Resolution` metadata field to provide
    interpretation.

    This entity is only applicable to derivative data.
  format: label
density:
  name: Density
  entity: den
  description: |
    Density of non-parametric surfaces.
    MUST have a corresponding `Density` metadata field to provide
    interpretation.

    This entity is only applicable to derivative data.
  format: label
label:
  name: Label
  entity: label
  description: |
    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.
  format: label
description:
  name: Description
  entity: desc
  description: |
    When necessary to distinguish two files that do not otherwise have a
    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.

    This entity is only applicable to derivative data.
  format: label