Merge pull request #568 from tsalo/enh/entity-definitions

[INFRA] Move entity definitions to a separate page

mkdocs.yml

@@ -48,6 +48,7 @@ nav:
         - MEG file formats: 99-appendices/06-meg-file-formats.md
         - MEG systems: 99-appendices/07-meg-systems.md
         - Coordinate systems: 99-appendices/08-coordinate-systems.md
+        - Entities: 99-appendices/09-entities.md
       - Changelog: CHANGES.md
     - The BIDS Starter Kit:
       - GitHub repository: https://github.com/bids-standard/bids-starter-kit

src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md

@@ -141,21 +141,20 @@ modalities include:
 If the structural images included in the dataset were defaced (to protect
 identity of participants) one MAY provide the binary mask that was used to
 remove facial features in the form of `_defacemask` files.
-In such cases,  the OPTIONAL `mod-<label>` key/value pair corresponds to modality suffix,
+In such cases,  the OPTIONAL [`mod-<label>`](../99-appendices/09-entities.md#mod)
+key/value pair corresponds to modality suffix,
 such as T1w or inplaneT1, referenced by the defacemask image.
 For example, `sub-01_mod-T1w_defacemask.nii.gz`.
 
-#### The `run` entity
-
-If several scans of the same modality are acquired they MUST be indexed with a
-key-value pair: `_run-1`, `_run-2`, `_run-3` etc. (only nonnegative integers are allowed as
+If several scans of the same modality are acquired they MUST be indexed with the
+[`run-<index>`](../99-appendices/09-entities.md#run) key-value pair:
+`_run-1`, `_run-2`, `_run-3` etc. (only nonnegative integers are allowed as
 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 `acq` entity
-
-The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label the user
+The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
+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
@@ -168,9 +167,8 @@ 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.
 
-#### The `ce` entity
-
-Similarly the OPTIONAL `ce-<label>` key/value can be used to distinguish
+Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
+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.
@@ -184,9 +182,8 @@ fields specific to anatomical scans:
 | -----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ContrastBolusIngredient | OPTIONAL. Active ingredient of agent. Values MUST be one of: IODINE, GADOLINIUM, CARBON DIOXIDE, BARIUM, XENON Corresponds to DICOM Tag 0018,1048. |
 
-#### The `rec` entity
-
-Similarly, the OPTIONAL `rec-<label>` key/value can be used to distinguish
+Similarly, the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
+key/value can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
 ### Task (including resting state) imaging data
@@ -217,16 +214,19 @@ multiband acquisitions, one MAY also save the single-band reference image as
 type `sbref` (e.g. `sub-control01_task-nback_sbref.nii.gz`).
 
 Each task has a unique label that MUST only consist of letters and/or numbers
-(other characters, including spaces and underscores, are not allowed).
+(other characters, including spaces and underscores, are not allowed) with the
+[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
 Those labels MUST be consistent across subjects and sessions.
 
-If more than one run of the same task has been acquired a key/value pair:
-`_run-1`, `_run-2`, `_run-3` etc. MUST be used. If only one run was acquired the
+If more than one run of the same task has been acquired the
+[`run-<index>`](../99-appendices/09-entities.md#run) key/value pair MUST be used:
+`_run-1`, `_run-2`, `_run-3` etc. If only one run was acquired the
 `run-<index>` can be omitted. In the context of functional imaging a run is
 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>`](../99-appendices/09-entities.md#acq)
+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
@@ -235,22 +235,25 @@ 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>`](../99-appendices/09-entities.md#ce)
+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>`](../99-appendices/09-entities.md#rec)
+key/value can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
-Similarly the OPTIONAL `dir-<label>` and `rec-<label>` key/values
+Similarly the OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
+and [`rec-<label>`](../99-appendices/09-entities.md#rec) 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)
 for more information on `dir` field specification.
 
-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. For example:
+Multi-echo data MUST be split into one file per echo using the
+[`echo-<index>`](../99-appendices/09-entities.md#echo) key-value pair. For example:
 
 ```Text
 sub-01/
@@ -374,7 +377,8 @@ sub-<label>/[ses-<label>/]
 ```
 
 Diffusion-weighted imaging data acquired for that participant. The OPTIONAL
-`acq-<label>` key/value pair corresponds to a custom label the user may use to
+[`acq-<label>`](../99-appendices/09-entities.md#acq)
+key/value pair corresponds to a custom label the user may use to
 distinguish different set of parameters. For example this should be used when a
 study includes two diffusion images - one single band and one multiband. In such
 case two files could have the following names:
@@ -458,8 +462,10 @@ slashes. Here’s an example with multiple target scans:
 The IntendedFor field is OPTIONAL and in case the fieldmaps do not correspond to
 any particular scans it does not have to be filled.
 
-Multiple fieldmaps can be stored. In such case the `_run-1`, `_run-2` should be
-used. The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label
+Multiple fieldmaps can be stored.
+In such case the [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair should be
+used. The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
+key/value pair corresponds to a custom label
 the user may use to distinguish different set of parameters.
 
 #### Case 1: Phase difference image and at least one magnitude image
@@ -581,7 +587,8 @@ example
 }
 ```
 
-`label` value of `_dir-` can be set to arbitrary alphanumeric label (`[a-zA-Z0-9]+` for
+The `label` value of the [`dir-<label>`](../99-appendices/09-entities.md#dir) key/value pair
+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

src/04-modality-specific-files/02-magnetoencephalography.md

@@ -49,13 +49,13 @@ files of various nature: for example, CTF's `.ds` format, or BTi/4D.
 Yet other manufacturers split their files once they exceed a certain size
 limit. For example Neuromag/Elekta/Megin, which can produce several files
 for a single recording. Both `some_file.fif` and `some_file-1.fif` would
-belong to a single recording. In BIDS, the `split` entity is RECOMMENDED to
+belong to a single recording. In BIDS, the [`split`](../99-appendices/09-entities.md#split) entity is RECOMMENDED to
 deal with split files.
 Please refer to [Appendix VI](../99-appendices/06-meg-file-formats.md) for
 general information on how to deal with such manufacturer specifics and to see
 more examples.
 
-The `proc` label is analogous to `rec` for MR and denotes a variant of a file
+The [`proc-<label>`](../99-appendices/09-entities.md#proc) entity is analogous to [`rec-<label>`](../99-appendices/09-entities.md#proc) 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 (e.g. sss, tsss,
 trans, quat, mc, etc.), which some installations impose to be run on raw data
@@ -379,7 +379,7 @@ taped to the skin. Please note that the photos may need to be cropped or blurred
 to conceal identifying features prior to sharing, depending on the terms of the
 consent given by the participant.
 
-The `acq` parameter can be used to indicate acquisition of different photos of
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) entity can be used to indicate acquisition of different photos of
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA)).
 
@@ -403,7 +403,7 @@ This file is RECOMMENDED.
 
 The 3-D locations of points that describe the head shape and/or EEG
 electrode locations can be digitized and stored in separate files. The
-`*_acq-<label>` can be used when more than one type of digitization in done for
+[`acq-<label>`](../99-appendices/09-entities.md#acq) entity can be used when more than one type of digitization in done for
 a session, for example when the head points are in a separate file from the EEG
 locations. These files are stored in the specific format of the 3-D digitizer’s
 manufacturer (see [Appendix VI](../99-appendices/06-meg-file-formats.md)).
@@ -429,9 +429,9 @@ In the context of BIDS it is RECOMMENDED to perform an empty-room recording for
 each experimental session.
 It is RECOMMENDED to store the empty-room recording inside a subject folder
 named `sub-emptyroom`.
-The label for the `task-<label>` entity in the empty-room recording SHOULD be
+The label for the [`task-<label>`](../99-appendices/09-entities.md#task) entity in the empty-room recording SHOULD be
 set to `noise`.
-If a `session-<label>` entity is present, its label SHOULD be the date of the
+If a [`session-<label>`](../99-appendices/09-entities.md#ses) entity is present, its label SHOULD be the date of the
 empty-room recording in the format `YYYYMMDD`, i.e., `ses-YYYYMMDD`.
 The `scans.tsv` file containing the date and time of the acquisition SHOULD
 also be included.

src/04-modality-specific-files/03-electroencephalography.md

@@ -315,7 +315,7 @@ REF   -0.0742   -0.0200  -0.0100   cup       Ag/AgCl
 GND   0.0742    -0.0200  -0.0100   cup       Ag/AgCl
 ```
 
-The `acq` parameter can be used to indicate acquisition of the same data. For
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair can be used to indicate acquisition of the same data. For
 example, this could be the recording of electrode positions with a different
 electrode position recording device, or repeated digitization before and after
 the recording.
@@ -439,7 +439,7 @@ Please note that the photos may need to be cropped or blurred to conceal
 identifying features prior to sharing, depending on the terms of the consent
 given by the participant.
 
-The `acq` parameter can be used to indicate acquisition of different photos of
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair can be used to indicate acquisition of different photos of
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA).
 

src/04-modality-specific-files/04-intracranial-electroencephalography.md

@@ -311,7 +311,7 @@ that coordinates are expected in cartesian coordinates according to the
 `*_coordsystem.json`. If an `*_electrodes.tsv` file is specified, a
 `*_coordsystem.json` file MUST be specified as well.
 
-The optional space label (`*[_space-<label>]_electrodes.tsv`) can be used to
+The optional [`space-<label>`](../99-appendices/09-entities.md#space) entity (`*[_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](../99-appendices/08-coordinate-systems.md)
@@ -325,7 +325,7 @@ For examples:
     space)
 
 When referring to the `*_electrodes.tsv` file in a certain _space_ as defined
-above, the `space-<label>` of the accompanying `*_coordsystem.json` MUST
+above, the [`space-<label>`](../99-appendices/09-entities.md#space) of the accompanying `*_coordsystem.json` MUST
 correspond.
 
 For example:
@@ -421,9 +421,9 @@ upper left pixel and (N,0) corresponding to the lower left pixel.
 ### Multiple coordinate systems
 
 If electrode positions are known in multiple coordinate systems (e.g., MRI, CT
-and MNI), these spaces can be distinguished by the optional `[_space-<label>]`
+and MNI), these spaces can be distinguished by the optional [`space-<label>`](../99-appendices/09-entities.md#space)
 field, see the [`*_electrodes.tsv`-section](#electrode-description-_electrodestsv)
-for more information. Note that the `[_space-<label>]` fields must correspond
+for more information. Note that the [`space-<label>`](../99-appendices/09-entities.md#space) fields must correspond
 between `*_electrodes.tsv` and `*_coordsystem.json` if they refer to the same
 data.
 
@@ -458,7 +458,7 @@ during surgery, or screenshots of a brain rendering with electrode positions.
 The photos may need to be cropped and/or blurred to conceal identifying features
 or entirely omitted prior to sharing, depending on obtained consent.
 
-If there are photos of the electrodes, the acquisition field should be specified
+If there are photos of the electrodes, the [`acq-<label>`](../99-appendices/09-entities.md#acq) entity should be specified
 with:
 
 -   `*_photo.jpg` in case of an operative photo
@@ -470,7 +470,7 @@ with:
 
 -   `*_acq-render#_photo.jpg` in case of a rendering
 
-The session label may be used to specify when the photo was taken.
+The [`ses-<label>`](../99-appendices/09-entities.md#ses) entity may be used to specify when the photo was taken.
 
 Example of the operative photo of ECoG electrodes (here is an annotated example in
 which electrodes and vasculature are marked, taken from Hermes et al.,

src/04-modality-specific-files/06-physiological-and-other-continuous-recordings.md

@@ -22,7 +22,7 @@ before the suffix.
 For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`,
 `<matches>` would correspond to `sub-control01_task-nback_run-1`.
 
-The `recording-<label>` entity can be used to distinguish between several
+The [`recording-<label>`](../99-appendices/09-entities.md#recording) entity can be used to distinguish between several
 recording files.
 For example `sub-01_task-bart_recording-eyetracking_physio.tsv.gz` to contain
 the eyetracking data in a certain sampling frequency, and

src/04-modality-specific-files/07-behavioral-experiments.md

@@ -27,7 +27,7 @@ Additionally, events files that do not include the mandatory `onset` and
 `duration` columns can still be included, but should be labeled `_beh.tsv`
 rather than `_events.tsv`.
 
-The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label to
+The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label to
 distinguish different conditions present during multiple runs of the same task.
 For example, if a study includes runs of an n-back task, with deep brain
 stimulation turned on or off, the data files may be labelled