[FIX] Standardise use of "entity" definition across specification

src/02-common-principles.md

@@ -13,7 +13,7 @@ misunderstanding we clarify them here.
     purpose of a particular study. A dataset consists of data acquired from one
     or more subjects, possibly from multiple sessions.
 
-1.  **Subject** - a person or animal participating in the study.  Used
+1.  **Subject** - a person or animal participating in the study. Used
     interchangeably with term **Participant**.
 
 1.  **Session** - a logical grouping of neuroimaging and behavioral data
@@ -34,7 +34,7 @@ misunderstanding we clarify them here.
 
 1.  **Sample** - a sample pertaining to a subject such as tissue, primary cell
     or cell-free sample.
-    The `sample-<label>` key/value pair is used to distinguish between different
+    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.
@@ -120,8 +120,8 @@ misunderstanding we clarify them here.
     following `task-<label>` specification. Note that labels MUST not collide when
     casing is ignored (see [Case collision intolerance](#case-collision-intolerance)).
 
-1.  **`suffix`** - an alphanumeric value, located after the `key-value_` pairs (thus after
-    the final `_`), right before the **File extension**, for example, it is `eeg` in
+1.  **`suffix`** - an alphanumeric value, located after all **entities** and following
+    a final `_`, right before the **file extension**; for example, it is `eeg` in
     `sub-05_task-matchingpennies_eeg.vhdr`.
 
 1.  **File extension** - a portion of the file name after the left-most
@@ -155,8 +155,7 @@ specification.
 
 ## File name structure
 
-A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
-*extension*.
+A file name consists of a chain of *entities*, a *suffix* and an *extension*.
 Two prominent examples of entities are `subject` and `session`.
 
 For a data file that was collected in a given `session` from a given
@@ -175,7 +174,7 @@ be added for all subjects if at least one subject in the dataset has more than
 one session.
 If a `/ses-<label>` subfolder is included as part of the directory hierarchy,
 then the same [`ses-<label>`](./99-appendices/09-entities.md#ses)
-key/value pair MUST also be included as part of the file names themselves.
+entity MUST also be included as part of the file names themselves.
 Acquisition time of session can
 be defined in the [sessions file](03-modality-agnostic-files.md#sessions-file).
 
@@ -414,9 +413,9 @@ levels unless they are overridden by a file at the lower level. For example,
 TR to a specific value. If one of the runs has a different TR than the one
 specified in that file, another `sub-*_task-rest_bold.json` file can be placed
 within that specific series directory specifying the TR for that specific run.
-There is no notion of "unsetting" a key/value pair.
-Once a key/value pair is set in a given level in the dataset, lower down in
-the hierarchy that key/value pair will always have some assigned value.
+There is no notion of "unsetting" a key-value pair.
+Once a key-value pair is set in a given level in the dataset, lower down in
+the hierarchy that key-value pair will always have some assigned value.
 Files for a particular participant can exist only at participant level directory,
 that is, `/dataset/sub-*[/ses-*]/sub-*_T1w.json`. Similarly, any file that is not
 specific to a participant is to be declared only at top level of dataset for example:
@@ -496,8 +495,8 @@ with different value in the
 deeper level, that value will be applicable for that particular run/task NIfTI
 file/s. In other words, the `.json` file at the deeper level overrides values
 that are potentially also defined in the `.json` at a more shallow level. If the
-`.json` file at the more shallow level contains key-value-pairs that are not
-present in the `.json` file at the deeper level, these key-value-pairs are
+`.json` file at the more shallow level contains key-value pairs that are not
+present in the `.json` file at the deeper level, these key-value pairs are
 inherited by the `.json` file at the deeper level (but NOT vice versa!).
 
 ### Good practice recommendations
@@ -607,9 +606,9 @@ Example:
 }
 ```
 
-### Key/value files (dictionaries)
+### Key-value files (dictionaries)
 
-JavaScript Object Notation (JSON) files MUST be used for storing key/value
+JavaScript Object Notation (JSON) files MUST be used for storing key-value
 pairs. JSON files MUST be in UTF-8 encoding. Extensive documentation of the
 format can be found at [https://www.json.org/](https://www.json.org/),
 and at [https://tools.ietf.org/html/std90](https://tools.ietf.org/html/std90).
@@ -664,7 +663,7 @@ of `<index>`es.
 Please note that a given label or index is distinct from the "prefix"
 it refers to. For example `sub-01` refers to the `sub` entity (a
 subject) with the label `01`. The `sub-` prefix is not part of the subject
-label, but must be included in file names (similarly to other key names).
+label, but must be included in file names (similarly to other entities).
 
 ## Uniform Resource Indicator
 

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

@@ -217,8 +217,8 @@ 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>`](../99-appendices/09-entities.md#mod)
-key/value pair corresponds to modality suffix,
-such as T1w or inplaneT1, referenced by the defacemask image.
+entity corresponds to modality suffix,
+such as `T1w` or `inplaneT1`, referenced by the defacemask image.
 For example, `sub-01_mod-T1w_defacemask.nii.gz`.
 
 If several scans with the same acquisition parameters are acquired in the same session,
@@ -233,7 +233,7 @@ or different acquisition parameters indicated by
 then `run` is not needed to distinguish the scans and MAY be omitted.
 
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label the user
+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
@@ -247,7 +247,7 @@ distinction (for example, just between RARE and FLASH, or between RARE, FLASH, a
 FLASHsubsampled) remains at the discretion of the researcher.
 
 Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
-key/value can be used to distinguish
+entity 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.
@@ -265,7 +265,7 @@ fields specific to anatomical scans:
    }
 ) }}
 
-The [`part-<label>`](../99-appendices/09-entities.md#part) key/value pair is
+The [`part-<label>`](../99-appendices/09-entities.md#part) entity is
 used to indicate which component of the complex representation of the MRI
 signal is represented in voxel data.
 This entity is associated with the DICOM Tag `0008, 9208`.
@@ -299,10 +299,10 @@ For example, for `sub-01_part-phase_T1w.json`:
 }
 ```
 
-When there is only a magnitude image of a given type, the `part` key MAY be omitted.
+When there is only a magnitude image of a given type, the `part` entity MAY be omitted.
 
 Similarly, the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-key/value can be used to distinguish
+entity can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
 Structural MR images whose intensity is represented in a non-arbitrary scale
@@ -387,18 +387,18 @@ type `sbref` (for example, `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) with the
-[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
+[`task-<label>`](../99-appendices/09-entities.md#task) entity.
 Those labels MUST be consistent across subjects and sessions.
 
 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-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
 `_run-1`, `_run-2`, `_run-3`, and so on. 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>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label one may
+entity 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
@@ -408,24 +408,24 @@ 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>`](../99-appendices/09-entities.md#ce)
-key/value can be used to distinguish
+entity 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
+contrast agent. The key "`ContrastBolusIngredient`" MAY be also be added in the JSON
 file, with the same label.
 
 Similarly the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-key/value can be used to distinguish
+entity can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
 Similarly the OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-and [`rec-<label>`](../99-appendices/09-entities.md#rec) key/values
+and [`rec-<label>`](../99-appendices/09-entities.md#rec) entities
 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 using the
-[`echo-<index>`](../99-appendices/09-entities.md#echo) key-value pair. For example:
+[`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:
 
 {{ MACROS___make_filetree_example(
    {
@@ -453,7 +453,7 @@ Newly generated datasets SHOULD NOT use the `_phase` suffix, and the suffix will
 from the specification in the next major release.
 For backwards compatibility, `_phase` is considered equivalent to `_part-phase_bold`.
 When the `_phase` suffix is not used, each file shares the same
-name with the exception of the `part-<mag|phase>` or `part-<real|imag>` key/value.
+name with the exception of the `part-<mag|phase>` or `part-<real|imag>` entity.
 
 For example:
 
@@ -601,19 +601,19 @@ Currently supported image types include:
 {{ MACROS___make_filename_template(datatypes=["dwi"]) }}
 
 If more than one run of the same acquisition and direction has been acquired, the
-[`run-<index>`](../99-appendices/09-entities.md#run) key/value pair MUST be used:
+[`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
 `_run-1`, `_run-2`, `_run-3` (and so forth.)
-When there is only one scan of a given acquisition and direction, the run key MAY be
+When there is only one scan of a given acquisition and direction, the `run` entity MAY be
 omitted.
-The [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair is RECOMMENDED
+The [`run-<index>`](../99-appendices/09-entities.md#run) entity is RECOMMENDED
 to encode the splits of multipart DWI scans (see [below](#multipart-split-dwi-schemes).)
 
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label the user may use to
+entity corresponds to a custom label the user may use to
 distinguish different sets of parameters.
 
 The OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-key/value pair corresponds to a custom label the user may use to
+entity corresponds to a custom label the user may use to
 distinguish different sets of phase-encoding directions.
 
 **Combining multi- and single-band acquisitions**.
@@ -623,7 +623,7 @@ The single-band reference image MAY be stored with suffix `sbref` (for example,
 to be stored.
 
 Otherwise, if some gradient information is associated to the single-band diffusion
-image and a multi-band diffusion image also exists, the `acq-<label>` key/value pair
+image and a multi-band diffusion image also exists, the `acq-<label>` entity
 MUST be used to distinguish both images.
 In such a case, two files could have the following names:
 `sub-01_acq-singleband_dwi.nii.gz` and `sub-01_acq-multiband_dwi.nii.gz`.
@@ -754,7 +754,7 @@ runs instead:
 ) }}
 
 The `MultipartID` metadata MAY be used with the
-[`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair, for example:
+[`acq-<label>`](../99-appendices/09-entities.md#acq) entity, for example:
 
 {{ MACROS___make_filetree_example(
    {
@@ -970,10 +970,10 @@ using the following image types:
 Two OPTIONAL entities, following more general rules of the specification,
 are allowed across all the four scenarios:
 
--   The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair corresponds to a one-based index
+-   The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) entity corresponds to a one-based index
     to distinguish multiple fieldmaps with the same parameters.
 
--   The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label
+-   The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) entity corresponds to a custom label
     the user may use to distinguish different set of parameters.
 
 ### Expressing the MR protocol intent for fieldmaps
@@ -1136,7 +1136,7 @@ AFNI `3dqwarp`, and SPM.
 
 The [`dir-<label>`](../99-appendices/09-entities.md#dir) entity is REQUIRED
 for these files.
-This key-value pair MUST be used in addition to
+This entity MUST be used in addition to
 the REQUIRED `PhaseEncodingDirection` metadata field
 (see [File name structure](../02-common-principles.md#file-name-structure)).
 

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

@@ -314,7 +314,8 @@ Cz     0.0000   0.0714   0.0699   cup      Ag/AgCl
 REF    -0.0742  -0.0200  -0.0100  cup      Ag/AgCl
 ```
 
-The [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair can be used to indicate acquisition of the same data. For
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) entity 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.
@@ -436,7 +437,8 @@ 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-<label>`](../99-appendices/09-entities.md#acq) key/value pair 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).
 

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

@@ -16,10 +16,10 @@ rather than `_events.tsv`.
 
 Each task has a unique label that MUST only consist of letters and/or numbers
 (other characters, including spaces and underscores, are not allowed) with the
-[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
+[`task-<label>`](../99-appendices/09-entities.md#task) entity.
 Those labels MUST be consistent across subjects and sessions.
 
-The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label to
+The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) entity 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

src/05-derivatives/01-introduction.md

@@ -58,7 +58,7 @@ in [Derived dataset and pipeline description][derived-dataset-description].
 
 -   When necessary to distinguish two files that do not otherwise have a
     distinguishing entity, the [`_desc-<label>`](../99-appendices/09-entities.md#desc)
-    keyword-value SHOULD be used.
+    entity SHOULD be used.
     This includes the cases of needing to distinguish both differing inputs and
     differing outputs (for example, `_desc-T1w` and `_desc-T2w` to distinguish
     brain mask files derived from T1w and T2w images;

src/05-derivatives/03-imaging.md

@@ -303,7 +303,7 @@ Example:
 ) }}
 
 See [Common image-derived labels](#common-image-derived-labels)
-for reserved key values for [`label`](../99-appendices/09-entities.md#label).
+for reserved values for the [`label`](../99-appendices/09-entities.md#label) entity.
 
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example:

src/99-appendices/04-entity-table.md

@@ -1,6 +1,6 @@
 # Appendix IV: Entity table
 
-This section compiles the entities (key-value pairs) described throughout this
+This section compiles the entities (key-value pairs within file names) described throughout this
 specification, and establishes a common order within a filename.
 For example, if a file has an acquisition and reconstruction label, the
 acquisition entity must precede the reconstruction entity.

src/99-appendices/06-meg-file-formats.md

@@ -317,9 +317,9 @@ For this reason, the marker file extension was later modernized to `.mrk` to bet
 However again, to preserve backwards compatibility, `.sqd` is still a valid extension for the marker file(s).
 
 If there are multiple files with marker coils, the marker files must have the
-`acq-<label>` parameter and no more that two marker files may be associated with
+`acq-<label>` entity and no more that two marker files may be associated with
 one raw data file.
-While the acquisition parameter can take any value, it is RECOMMENDED that if
+While the acquisition entity can take any value, it is RECOMMENDED that if
 the two marker measurements occur before and after the raw data acquisition,
 `pre` and `post` are used to differentiate the two situations.
 

src/99-appendices/09-entities.md

@@ -1,6 +1,6 @@
 # Appendix IX: Entities
 
-This section compiles the entities (key-value pairs) described throughout this
+This section compiles the entities (key-value pairs within file names) described throughout this
 specification, and describes each.
 
 A general introduction to entities is given in the section on