entities.yaml

---
# This file describes entities present in BIDS filenames.
# WARNING: The entities are presented here in alphabetical order!
# The appropriate order of entities in filenames is defined in `rules/entities.yaml`,
# rather than this file (`objects/entities.yaml`).
acquisition:
  name: acq
  display_name: Acquisition
  description: |
    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.
  type: string
  format: label
atlas:
  name: atlas
  display_name: Atlas
  description: |
    The `atlas-<label>` entity identifies files that are part of, or derived from, an atlas.
  type: string
  format: label
ceagent:
  name: ce
  display_name: Contrast Enhancing Agent
  description: |
    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.
  type: string
  format: label
cohort:
  name: cohort
  display_name: Cohort
  description: |
    A set of subjects sharing one or more common characteristics.

    In the context of a template, the `cohort-<label>` entity identifies a subset of
    subjects or sessions that were used to construct template variations.
    For example, a developmental template may use scans from participants of different ages,
    longitudinal sessions of the same participants, or a combination of the two.
  type: string
  format: label
chunk:
  name: chunk
  display_name: Chunk
  description: |
    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.
  type: string
  format: index
density:
  name: den
  display_name: Density
  description: |
    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.
  type: string
  format: label
description:
  name: desc
  display_name: Description
  description: |
    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.
  type: string
  format: label
direction:
  name: dir
  display_name: Phase-Encoding Direction
  description: |
    The `dir-<label>` entity can be set to an arbitrary legitimate 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.

    Labels need not follow any particular convention and in case of conflict,
    JSON metadata MUST take precedence in interpreting an image.

    For example, `dir-j0` and `dir-j1` can indicate `"PhaseEncodingDirection": "j"` and `"j-"` (or vice versa),
    identifying the phase-encoding axis while avoiding indicating polarity.
    However, in case of a dataset indicating `dir-j0` with `"PhaseEncodingDirection": "i"`, the
    JSON metadata overrides the entity `dir-` setting.

    The use of generic labels, such as `dir-reference` and `dir-reversed`, is RECOMMENDED
    to avoid any possible inconsistency.

    To avoid inconsistency, if the `<label>` is `AP`, `PA`, `LR`, `RL`, `SI`, or `IS`,
    then the `"PhaseEncodingDirection"` SHOULD correspond to the data
    axis that most closely aligns with the cardinal direction and orientation.
    For example, `dir-PA` and `dir-AP` for an image in RAS+ orientation SHOULD have
    `"PhaseEncodingDirection": "j"` and `"j-"`, respectively.
  type: string
  format: label
echo:
  name: echo
  display_name: Echo
  description: |
    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.
  type: string
  format: index
flip:
  name: flip
  display_name: Flip Angle
  description: |
    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.
  type: string
  format: index
hemisphere:
  name: hemi
  display_name: Hemisphere
  description: |
    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.
  type: string
  format: label
  enum:
    - $ref: objects.enums.left_hemisphere.value
    - $ref: objects.enums.right_hemisphere.value
inversion:
  name: inv
  display_name: Inversion Time
  description: |
    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.
  type: string
  format: index
label:
  name: label
  display_name: 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.
  type: string
  format: label
modality:
  name: mod
  display_name: Corresponding Modality
  description: |
    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`.
  type: string
  format: label
mtransfer:
  name: mt
  display_name: Magnetization Transfer
  description: |
    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.
  type: string
  format: label
  enum:
    - $ref: objects.enums.on__mtransfer.value
    - $ref: objects.enums.off__mtransfer.value
nucleus:
  name: nuc
  display_name: Nucleus
  description: |
    The `nuc-<label>` entity can be used to distinguish acquisitions tuned
    to detect different nuclei.
    The label is the name of the nucleus or nuclei, which corresponds to DICOM Tag `0018, 9100`.
    If present in the filename, `"ResonantNucleus"` MUST also be included in
    the associated metadata.
  type: string
  format: label
part:
  name: part
  display_name: 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>` 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.
  type: string
  format: label
  enum:
    - $ref: objects.enums.magnitude.value
    - $ref: objects.enums.phase.value
    - $ref: objects.enums.real.value
    - $ref: objects.enums.imaginary.value
processing:
  name: proc
  display_name: Processed (on device)
  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 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.
  type: string
  format: label
reconstruction:
  name: rec
  display_name: Reconstruction
  description: |
    The `rec-<label>` entity can be used to distinguish different reconstruction algorithms
    (for example, `MoCo` for the ones using motion correction).
  type: string
  format: label
recording:
  name: recording
  display_name: Recording
  description: |
    The `recording-<label>` entity can be used to distinguish continuous recording files.

    This entity is commonly applied when continuous recordings are from different acquisition instruments,
    or 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`.
  type: string
  format: label
resolution:
  name: res
  display_name: Resolution
  description: |
    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.
  type: string
  format: label
run:
  name: run
  display_name: Run
  description: |
    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>`](SPEC_ROOT/appendices/entities.md#run) 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>`](SPEC_ROOT/appendices/entities.md#ses),
    or different acquisition parameters indicated by
    [`acq-<label>`](SPEC_ROOT/appendices/entities.md#acq),
    then `run` is not needed to distinguish the scans and MAY be omitted.
  type: string
  format: index
sample:
  name: sample
  display_name: Sample
  description: |
    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.
  type: string
  format: label
segmentation:
  name: seg
  display_name: Segmentation
  description: |
    The `seg-<label>` key/value pair corresponds to a custom label the user
    MAY use to distinguish specific partitions of the data space
    (segmentations or parcellations).

    Segmentations and parcellations MAY or MAY NOT be associated with
    [atlases](SPEC_ROOT/common-principles.md#definitions).
    Therefore, `seg-<label>` SHOULD NOT be used to designate
    [atlases](SPEC_ROOT/common-principles.md#definitions).
    Please refer to the [template and atlas section](SPEC_ROOT/derivatives/atlas.md)
    for detailed specifications on their combined use.
    When a segmentation is a *realization* of an atlas' segmentation or parcellation,
    `seg-<label>` SHOULD be employed to distinguish them.
    For example, the [Yeo 2011 atlas](https://doi.org/10.1152/jn.00338.2011)
    is distributed within *FreeSurfer* with two different parcellations:
    the *7 networks* MAY be described with `seg-7n`, for instance, and
    the *17 networks* MAY correspondingly be described with `seg-17n`.

    This entity is only applicable to derivative data.
  type: string
  format: label
scale:
  name: scale
  display_name: Scale
  description: |
    The `scale-<label>` key/value pair corresponds to a custom label the user
    MAY use to distinguish segmentations that entail different levels of
    *regional resolution* (scales), often indicated by the number of ROIs.
    See ([Bijsterbosch et al., 2020](https://doi.org/10.1038/s41593-020-00726-z))
    for further details on *regional resolution* or, as defined by the authors of
    the manuscript, the *brain units*.

    For example, the [Schaefer 2018 atlas](https://doi.org/10.1093/cercor/bhx179)
    is distributed within *FreeSurfer* with ten different scales
    (100, 200, 300, 400, 500, 600, 700, 800, 900, and 1000 regions) for each of
    its three different parcellations (*7 networks*, *17 networks*, and
    *Kong's variation of 17 networks*).

    This entity is only applicable to derivative data.
  type: string
  format: label
session:
  name: ses
  display_name: Session
  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).
  type: string
  format: label
space:
  name: space
  display_name: Space
  description: |
    The `space-<label>` entity indicates the coordinate system for interpreting
    spatial coordinates.
    For sensor-based modalities, such as EEG/MEG/iEEG,
    the space indicates how sensor positions are reported;
    for imaging modalities,
    the space indicates a reference image to which a file has been aligned.
    A list of common spaces is defined in the
    [Coordinate Systems Appendix](SPEC_ROOT/appendices/coordinate-systems.md),
    and these SHOULD be used as `<label>` values for data reported in those
    spaces.

    Note that the space entity is broadly applicable to derivative data,
    but is only defined for a subset of raw data types.
    For particular use cases, `<label>` may be restricted to a set of enumerated values.
  type: string
  format: label
split:
  name: split
  display_name: Split
  description: |
    In the case of long data recordings that exceed a file size of 2Gb,
    `.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 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](SPEC_ROOT/modality-agnostic-files/data-summary-files.md#scans-file).
  type: string
  format: index
stain:
  name: stain
  display_name: Stain
  description: |
    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.
  type: string
  format: label
subject:
  name: sub
  display_name: Subject
  description: |
    A person or animal participating in the study.
  type: string
  format: label
task:
  name: task
  display_name: Task
  description: |
    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](SPEC_ROOT/modality-agnostic-files/events.md#events),
    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`).
  type: string
  format: label
template:
  name: tpl
  display_name: Template
  description: |
    A standardized space of analysis specified or generated by one or more averages of features
    with respect to which group-level and atlas-derived results are provided.
    The `<label>` SHOULD follow the modality-specific conventions listed in the
    [Coordinate Systems Appendix](SPEC_ROOT/appendices/coordinate-systems.md).
  type: string
  format: label
tracer:
  name: trc
  display_name: Tracer
  description: |
    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.
  type: string
  format: label
volume:
  name: voi
  display_name: Volume of Interest
  description: |
    The `voi-<label>` entity can be used to distinguish acquisitions localized to different regions.
    The label SHOULD be the name of the body region or part scanned.
    If used, the fields `"BodyPart"` and `"BodyPartDetails"` MUST be defined in the JSON file.
    `BodyPartDetailsOntology` is OPTIONAL to also include.
  type: string
  format: label
track:
  name: track
  display_name: Tractography Method
  description: |
    The `track-<label>` entity identifies the tractography method
    employed to reconstruct white matter fiber streamlines.
  type: string
  format: label
tracksys:
  name: tracksys
  display_name: Tracking System
  description: |
    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.
  type: string
  format: label
tract:
  name: tract
  display_name: Anatomical Tract
  description: |
    The `tract-<label>` entity identifies the white matter fiber
    anatomical/structural entity that is imaged through a
    tractogram (for example, `tract-wholebrain` would correspond to a
    whole-brain tractogram, whereas `tract-ArcuateFasciculus` would
    correspond to a tractogram of the arcuate fasciculus).
  type: string
  format: label