[ENH] Add Glossary of terms/abbreviations used in the specification

src/02-common-principles.md

@@ -6,56 +6,74 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
 "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
 interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)].
 
-Throughout this specification we use a list of terms. To avoid
+Throughout this specification we use a list of terms and abbreviations. To avoid
 misunderstanding we clarify them here.
 
-1.  Dataset - a set of neuroimaging and behavioral data acquired for a purpose
-    of a particular study. A dataset consists of data acquired from one or more
-    subjects, possibly from multiple sessions.
+1.  **Dataset** - a set of neuroimaging and behavioral data acquired for a
+    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.
+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 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
+1.  **Session** - 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 (e.g., training).
 
-1.  Data acquisition - a continuous uninterrupted block of time during which a
-    brain scanning instrument was acquiring data according to particular
+1.  **Data acquisition** - a continuous uninterrupted block of time during which
+    a brain scanning instrument was acquiring data according to particular
     scanning sequence/protocol.
 
-1.  Data type - a functional group of different types of data. In BIDS we define
-    eight data types: func (task based and resting state functional MRI), dwi
-    (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as
-    field maps), anat (structural imaging such as T1, T2, etc.), meg
-    (magnetoencephalography), eeg (electroencephalography), ieeg (intracranial
-    electroencephalography), beh (behavioral).
+1.  **Data type** - a functional group of different types of data. In BIDS we
+    define eight data types: `func` (task based and resting state functional MRI),
+    `dwi` (diffusion weighted imaging), `fmap` (field inhomogeneity mapping data
+    such as field maps), `anat` (structural imaging such as T1, T2, etc.), `meg`
+    (magnetoencephalography), `eeg` (electroencephalography), `ieeg` (intracranial
+    electroencephalography), `beh` (behavioral).
 
-1.  Task - a set of structured activities performed by the participant. Tasks
-    are usually accompanied by stimuli and responses, and can greatly vary in
-    complexity. For the purpose of this specification we consider the so-called
+1.  **Task** - a set of structured activities performed by the participant.
+    Tasks are usually accompanied by stimuli and responses, and can greatly vary
+    in complexity. For the purpose of this specification we consider the so-called
     "resting state" a task. 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.
 
-1.  Event - a stimulus or subject response recorded during a task. Each event
-    has an onset time and duration. Note that not all tasks will have recorded
-    events (e.g., resting state).
+1.  **Event** - a stimulus or subject response recorded during a task. Each
+    event has an onset time and duration. Note that not all tasks will have
+    recorded events (e.g., “resting state”).
 
-1.  Run - an uninterrupted repetition of data acquisition that has the same
+1.  **Run** - an uninterrupted repetition of data acquisition that has the same
     acquisition parameters and task (however events can change from run to run
     due to different subject response or randomized nature of the stimuli). Run
     is a synonym of a data acquisition.
 
+1.  **`<index>`** - a numeric value, possibly prefixed with arbitrary number of
+    0s for consistent indentation, e.g., it is `01` in `run-01` following
+    `run-<index>` specification.
+
+1.  **`<label>`** - an alphanumeric value, possibly prefixed with arbitrary
+    number of 0s for consistent indentation, e.g., it is `rest` in `task-rest`
+    following `task-<label>` specification.
+
+1.  **`suffix`** - a portion of the file name with `key-value_` pairs (thus after
+    the final `_`), right before the **File extension**, e.g., it is `eeg` in
+    `sub-05_task-matchingpennies_eeg.vhdr`.
+
+1.  **File extension** - a portion of the the file name after the left-most
+    period (`.`) preceded by any other alphanumeric. For example, `.gitignore` does
+    not have a file extension, but the file extension of `test.nii.gz` is `.nii.gz`.
+    Note that the left-most period is included in the file extension.
+
 ## Compulsory, optional, and additional data and metadata
 
 The following standard describes a way of arranging data and writing down
@@ -378,18 +396,18 @@ for more information.
 
 ## Participant names and other labels
 
-BIDS uses custom user-defined labels in several situations (naming of
-participants, sessions, acquisition schemes, etc.) Labels are strings and MUST
-only consist of letters (lower or upper case) and/or numbers. If numbers are
-used we RECOMMEND zero padding (e.g., `01` instead of `1` if you have more than
-nine subjects) to make alphabetical sorting more intuitive.
-
-Please note that a given label 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). In contrast to other labels, `run` and
-`echo` labels MUST be integers. Those labels MAY include zero padding, but this
-is NOT RECOMMENDED to maintain their uniqueness.
+BIDS allows for custom user-defined `<label>`s and `<index>`es e.g.,
+for naming of participants, sessions, acquisition schemes, etc. Note
+that they MUST consist only of allowed characters as described in
+[Definitions](02-common-principles.md#definitions) above. In `<index>`es
+we RECOMMEND using zero padding (e.g., `01` instead of `1` if you have more than
+nine subjects) to make alphabetical sorting more intuitive. Note that
+zero padding is NOT RECOMMENDED to maintain their uniqueness.
+
+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).
 
 ## Units