From fc1299010cdf66afb0075e0b9dc6000a4e28da11 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Fri, 15 Feb 2019 12:47:14 -0500
Subject: [PATCH 1/8] ENH: Add Glossary of terms/abbreviations used in the
 specification

---
 mkdocs.yml                       |  1 +
 src/99-appendices/09-glossary.md | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)
 create mode 100644 src/99-appendices/09-glossary.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 45a37ccbda..5c0ad74f37 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,5 +31,6 @@ 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
+        - Glossary: 99-appendices/09-glossary.md
       - Changelog: CHANGES.md
     - The BIDS Starter Kit: https://github.com/bids-standard/bids-starter-kit
diff --git a/src/99-appendices/09-glossary.md b/src/99-appendices/09-glossary.md
new file mode 100644
index 0000000000..865775d307
--- /dev/null
+++ b/src/99-appendices/09-glossary.md
@@ -0,0 +1,26 @@
+# Appendix IX: Glossary
+
+A number of terms are used throughout the specification
+
+- **file extension**:
+   a portion of the the file name after the left-most period (`.`) preceded by
+   any other alphanumeric (so `.gitignore` does not have a suffix)
+- **<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
+- **<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
+- **participant**:
+   a participant of the experiment. Used interchangeably with **subject**
+- **run**:
+   a separate data sequence/acquisition. Typically present to disambiguate
+   otherwise identically named data files
+- **session**:
+   a separate scanning/experiment session. Typically present if the same 
+   subjects participate in multiple sessions of the experiment 
+- **subject**:
+   a participant of the experiment. Used interchangeably with **participant**
+- **suffix**:
+   a portion of the file name with `key-value_` pairs (thus after the final `_`),
+   right before the **file extension**
\ No newline at end of file

From 0fc6c23941baa166a26587c8b4764944f7db8aab Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 9 May 2019 20:54:00 -0400
Subject: [PATCH 2/8] RF: move glossary terms into common principles
 definitions

---
 mkdocs.yml                       |  1 -
 src/02-common-principles.md      | 21 +++++++++++++++++++--
 src/99-appendices/09-glossary.md | 26 --------------------------
 3 files changed, 19 insertions(+), 29 deletions(-)
 delete mode 100644 src/99-appendices/09-glossary.md

diff --git a/mkdocs.yml b/mkdocs.yml
index 5c0ad74f37..45a37ccbda 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,6 +31,5 @@ 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
-        - Glossary: 99-appendices/09-glossary.md
       - Changelog: CHANGES.md
     - The BIDS Starter Kit: https://github.com/bids-standard/bids-starter-kit
diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 0d15b1e80b..bdd62dbe9f 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -6,14 +6,15 @@ 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.  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
@@ -55,6 +56,22 @@ misunderstanding we clarify them here.
     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.
+
+1.  File extension - a portion of the the file name after the left-most period
+    (`.`) preceded by any other alphanumeric (so `.gitignore` does not have a
+    suffix)
+
+
 ## Compulsory, optional, and additional data and metadata
 
 The following standard describes a way of arranging data and writing down
diff --git a/src/99-appendices/09-glossary.md b/src/99-appendices/09-glossary.md
deleted file mode 100644
index 865775d307..0000000000
--- a/src/99-appendices/09-glossary.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Appendix IX: Glossary
-
-A number of terms are used throughout the specification
-
-- **file extension**:
-   a portion of the the file name after the left-most period (`.`) preceded by
-   any other alphanumeric (so `.gitignore` does not have a suffix)
-- **<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
-- **<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
-- **participant**:
-   a participant of the experiment. Used interchangeably with **subject**
-- **run**:
-   a separate data sequence/acquisition. Typically present to disambiguate
-   otherwise identically named data files
-- **session**:
-   a separate scanning/experiment session. Typically present if the same 
-   subjects participate in multiple sessions of the experiment 
-- **subject**:
-   a participant of the experiment. Used interchangeably with **participant**
-- **suffix**:
-   a portion of the file name with `key-value_` pairs (thus after the final `_`),
-   right before the **file extension**
\ No newline at end of file

From 0fe152972a3c10b15966a961681b101edb4164e1 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 9 May 2019 21:00:25 -0400
Subject: [PATCH 3/8] ENH: use formatting (**, ``) for Terms/Abbreviations
 items

Also added consistency in referencing "resting state" task
---
 src/02-common-principles.md | 75 ++++++++++++++++++-------------------
 1 file changed, 37 insertions(+), 38 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index bdd62dbe9f..feb91e053f 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -9,19 +9,19 @@ interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)].
 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.  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.  **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.  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
     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
@@ -29,49 +29,48 @@ misunderstanding we clarify them here.
     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
-    six 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), beh (behavioral).
+1.  **Data type** - a functional group of different types of data. In BIDS we
+    define six 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), `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.  **`<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.  **`<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.
+1.  **`suffix`** - a portion of the file name with `key-value_` pairs (thus after
+    the final `_`), right before the **File extension**.
 
-1.  File extension - a portion of the the file name after the left-most period
-    (`.`) preceded by any other alphanumeric (so `.gitignore` does not have a
+1.  **File extension** - a portion of the the file name after the left-most
+    period (`.`) preceded by any other alphanumeric (so `.gitignore` does not have a
     suffix)
 
-
 ## Compulsory, optional, and additional data and metadata
 
 The following standard describes a way of arranging data and writing down

From 0b999c3741a836766d4b28d6e43506c23e7f5e0b Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 9 May 2019 21:31:00 -0400
Subject: [PATCH 4/8] RF: reword/shorten "Participant names and other labels"
 referring to <label>s and <index>es

---
 src/02-common-principles.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index feb91e053f..ffb29fa610 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -339,15 +339,13 @@ Example:
 
 ## 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 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 use only allowed characters as described in [Definitions](02-common-principles.md#definitions)
+above. In `<index>`es we RECOMMEND zero padding (e.g., `01` instead of `1`
+if you have more than nine subjects) to make alphabetical sorting more
+intuitive. Zero padding is NOT RECOMMENDED to be used to maintain their
+uniqueness.
 
 ## Units
 

From 1b9e8e61af48fdaaf131852a879f455d98f1c564 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Fri, 22 May 2020 11:55:30 -0400
Subject: [PATCH 5/8] ENH: provide an example for a suffix based on an
 _eeg.vhdr filename

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/02-common-principles.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 9ecfcbd00b..d44d1b0b8a 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -66,7 +66,8 @@ misunderstanding we clarify them here.
     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**.
+    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 (so `.gitignore` does not have a

From cd1c10eeaf2df1806dcd1dd8954f55424d86cdf1 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Fri, 22 May 2020 11:58:36 -0400
Subject: [PATCH 6/8] ENH: Include leading . within definition of the file
 extension

This would
- match current use of "extension" in BIDS text
- match use within bids-validator messages
- stay inline with filename splitting utilities available in Python and Matlab

Note: it is different from PyBIDS which ATM does not require leading
'.' for `extension` specification in the queries.

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/02-common-principles.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index d44d1b0b8a..d41bc387b3 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -70,8 +70,9 @@ misunderstanding we clarify them here.
     `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 (so `.gitignore` does not have a
-    suffix)
+    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
 

From 60dfdb6e2b708d5682aa79f8aaebb37ee8f47436 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Fri, 22 May 2020 13:48:04 -0400
Subject: [PATCH 7/8] ENH: make NOT RECOMMENDED stronger (SHOULD NOT) for zero
 padding for uniqueness

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/02-common-principles.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index d41bc387b3..36c9f8d412 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -402,7 +402,8 @@ 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.
+zero padding SHOULD NOT be used to merely maintain uniqueness
+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

From a3605326afb7f8de14d1545a1e2e16badf528660 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Fri, 22 May 2020 16:52:03 -0400
Subject: [PATCH 8/8] Specify that suffix must be alphanumeric

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/02-common-principles.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 36c9f8d412..a00d1e597c 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -65,7 +65,7 @@ misunderstanding we clarify them here.
     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
+1.  **`suffix`** - an alphanumeric value, located after the `key-value_` pairs (thus after
     the final `_`), right before the **File extension**, e.g., it is `eeg` in
     `sub-05_task-matchingpennies_eeg.vhdr`.