From 4874e64ca6c662d03aef4699d747c53089a716a4 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 12 Jul 2019 15:59:01 +0200
Subject: [PATCH 01/14] transpose entity table

---
 src/99-appendices/04-entity-table.md | 35 ++++++++++++++++------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index cb8d96539b..b83431ecaf 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -7,18 +7,23 @@ precede the reconstruction entity. REQUIRED and OPTIONAL entities for a given
 file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
-| Entity                   | Format              | anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | anat<br>(defacemask) | func<br>(bold sbref events) | func<br>(physio stim) | dwi<br>(dwi bvec bval) | fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap) | fmap<br>(epi) | beh<br>(events stim physio) | meg<br>  | eeg<br>  | ieeg<br> | channels<br>(meg/eeg/ieeg) | headshape<br>(meg) | markers<br>(meg) | photo<br>(meg/eeg/ieeg) | electrodes<br>(eeg/ieeg) | events<br>(meg/eeg/ieeg) |
-| :----------------------- | :------------------ | :--------------------------------------------------------------------------------------------- | :------------------- | :-------------------------- | :-------------------- | :--------------------- | :------------------------------------------------------------------------- | :------------ | :-------------------------- | :------- | :------- | :------- | :------------------------- | :----------------- | :--------------- | :---------------------- | :----------------------- | :----------------------- |
-| Subject                  | `sub-<label>`       | REQUIRED                                                                                       | REQUIRED             | REQUIRED                    | REQUIRED              | REQUIRED               | REQUIRED                                                                   | REQUIRED      | REQUIRED                    | REQUIRED | REQUIRED | REQUIRED | REQUIRED                   | REQUIRED           | REQUIRED         | REQUIRED                | REQUIRED                 | REQUIRED                 |
-| Session                  | `ses-<label>`       | OPTIONAL                                                                                       | OPTIONAL             | OPTIONAL                    | OPTIONAL              | OPTIONAL               | OPTIONAL                                                                   | OPTIONAL      | OPTIONAL                    | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL                   | OPTIONAL           | OPTIONAL         | OPTIONAL                | OPTIONAL                 | OPTIONAL                 |
-| Task                     | `task-<label>`      |                                                                                                |                      | REQUIRED                    | REQUIRED              |                        |                                                                            |               | REQUIRED                    | REQUIRED | REQUIRED | REQUIRED | REQUIRED                   |                    | OPTIONAL         |                         |                          | REQUIRED                 |
-| Acquisition              | `acq-<label>`       | OPTIONAL                                                                                       | OPTIONAL             | OPTIONAL                    | OPTIONAL              | OPTIONAL               | OPTIONAL                                                                   | OPTIONAL      |                             | OPTIONAL | OPTIONAL | OPTIONAL |                            | OPTIONAL           | OPTIONAL         | OPTIONAL                | OPTIONAL                 |                          |
-| Contrast Enhancing Agent | `ce-<label>`        | OPTIONAL                                                                                       | OPTIONAL             | OPTIONAL                    |                       |                        |                                                                            | OPTIONAL      |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Reconstruction           | `rec-<label>`       | OPTIONAL                                                                                       | OPTIONAL             | OPTIONAL                    | OPTIONAL              |                        |                                                                            |               |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Phase-Encoding Direction | `dir-<label>`       |                                                                                                |                      | OPTIONAL                    |                       | OPTIONAL               |                                                                            | REQUIRED      |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Run                      | `run-<index>`       |                                                                                                |                      | OPTIONAL                    | OPTIONAL              | OPTIONAL               | OPTIONAL                                                                   | OPTIONAL      |                             | OPTIONAL | OPTIONAL | OPTIONAL | OPTIONAL                   |                    |                  |                         |                          | OPTIONAL                 |
-| Corresponding modality   | `mod-<label>`       |                                                                                                | OPTIONAL             |                             |                       |                        |                                                                            |               |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Echo                     | `echo-<index>`      |                                                                                                |                      | OPTIONAL                    |                       |                        |                                                                            |               |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Recording                | `recording-<label>` |                                                                                                |                      |                             | OPTIONAL              |                        |                                                                            |               |                             |          |          |          |                            |                    |                  |                         |                          |                          |
-| Processed (on device)    | `proc-<label>`      |                                                                                                |                      |                             | OPTIONAL              |                        |                                                                            |               |                             | OPTIONAL |          |          |                            |                    |                  |                         |                          |                          |
-| Space                    | `space-<label>`     |                                                                                                |                      |                             |                       |                        |                                                                            |               |                             |          |          |          |                            | OPTIONAL           | OPTIONAL         |                         | OPTIONAL                 |                          |
+Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space
+---                                                                                            | ---           | ---           | ---            | ---           | ---                      | ---            | ---                      | ---           | ---                    | ---            | ---                 | ---                   | ---
+Format                                                                                         | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>`             | `rec-<label>`  | `dir-<label>`            | `run-<index>` | `mod-<label>`          | `echo-<index>` | `recording-<label>` | `proc-<label>`        | `space-<label>`
+anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               |                        |                |                     |                       |
+anat<br>(defacemask)                                                                           | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               | OPTIONAL               |                |                     |                       |
+func<br>(bold sbref events)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      | OPTIONAL                 | OPTIONAL       | OPTIONAL                 | OPTIONAL      |                        | OPTIONAL       |                     |                       |
+func<br>(physio stim)                                                                          | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          | OPTIONAL       |                          | OPTIONAL      |                        |                | OPTIONAL            | OPTIONAL              |
+dwi<br>(dwi bvec bval)                                                                         | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                | OPTIONAL                 | OPTIONAL      |                        |                |                     |                       |
+fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap)                     | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
+fmap<br>(epi)                                                                                  | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 |                | REQUIRED                 | OPTIONAL      |                        |                |                     |                       |
+beh<br>(events stim physio)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          |               |                        |                |                     |                       |
+meg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     | OPTIONAL              |
+eeg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
+ieeg<br>                                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
+channels<br>(meg/eeg/ieeg)                                                                     | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
+headshape<br>(meg)                                                                             | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
+markers<br>(meg)                                                                               | REQUIRED      | OPTIONAL      | OPTIONAL       | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
+photo<br>(meg/eeg/ieeg)                                                                        | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       |
+electrodes<br>(eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
+events<br>(meg/eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |

From bea27b0770aa10dfddb39328d0c1f1fb10fa08ab Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 12 Jul 2019 16:39:37 +0200
Subject: [PATCH 02/14] try links

---
 .../01-magnetic-resonance-imaging-data.md                 | 2 +-
 src/99-appendices/04-entity-table.md                      | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 77bbeb1d82..a335d877f5 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -142,7 +142,7 @@ 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 OPTIONAL `acq-<label>` key/value pair corresponds to a custom label the user
+The OPTIONAL <a id="#entity-acq">`acq-<label>`</a> 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
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index b83431ecaf..e2d7db6429 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -7,6 +7,14 @@ precede the reconstruction entity. REQUIRED and OPTIONAL entities for a given
 file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
+- linking to entities
+  - <a href="#entity-sub">sub</a>
+  - <a href="#entity-ses">ses</a>
+  - <a href="#entity-task">task</a>
+  - <a href="#entity-acq">acq</a>
+
+
+
 Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space
 ---                                                                                            | ---           | ---           | ---            | ---           | ---                      | ---            | ---                      | ---           | ---                    | ---            | ---                 | ---                   | ---
 Format                                                                                         | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>`             | `rec-<label>`  | `dir-<label>`            | `run-<index>` | `mod-<label>`          | `echo-<index>` | `recording-<label>` | `proc-<label>`        | `space-<label>`

From 2e1cccd7c2e65c353d8d4e03046696760d1b025c Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 12 Jul 2019 16:44:33 +0200
Subject: [PATCH 03/14] try fix links

---
 .../01-magnetic-resonance-imaging-data.md                       | 2 ++
 src/99-appendices/04-entity-table.md                            | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index a335d877f5..03529e186c 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -1,5 +1,7 @@
 # Magnetic Resonance Imaging data
 
+- <a href="#entity-acq">acq</a>
+
 ## Common metadata fields
 
 MR Data described in sections 8.3.x share the following RECOMMENDED metadata
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index e2d7db6429..e2d1bbe406 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -12,6 +12,8 @@ file type are denoted. Entity formats indicate whether the value is alphanumeric
   - <a href="#entity-ses">ses</a>
   - <a href="#entity-task">task</a>
   - <a href="#entity-acq">acq</a>
+  - - <a href="../04-modality-specific-files/01-magnetic-resonance-imaging-data#entity-acq">fixed link acq</a>
+
 
 
 

From 5d9c33f177e4a3a4789e32598a96738e1a2fd994 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 12 Jul 2019 17:00:15 +0200
Subject: [PATCH 04/14] try links via tiny headings

---
 .../01-magnetic-resonance-imaging-data.md           | 12 +++++++++---
 src/99-appendices/04-entity-table.md                | 13 ++++---------
 2 files changed, 13 insertions(+), 12 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 03529e186c..0177ffd2ee 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -1,7 +1,5 @@
 # Magnetic Resonance Imaging data
 
-- <a href="#entity-acq">acq</a>
-
 ## Common metadata fields
 
 MR Data described in sections 8.3.x share the following RECOMMENDED metadata
@@ -138,13 +136,17 @@ modalities include:
 | Inplane T2         | inplaneT2        | T2-weighted anatomical image matched to functional acquisition                                                                                                                                                                          |
 | Angiography        | angio            |                                                                                                                                                                                                                                         |
 
+###### 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 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 OPTIONAL <a id="#entity-acq">`acq-<label>`</a> key/value pair corresponds to a custom label the user
+###### The `acq` entity
+
+The OPTIONAL `acq-<label>` 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
@@ -157,11 +159,15 @@ 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
 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.
 
+###### The `rec` entity
+
 Similarly the OPTIONAL `rec-<label>` key/value can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index e2d1bbe406..f68f0339a7 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -7,15 +7,10 @@ precede the reconstruction entity. REQUIRED and OPTIONAL entities for a given
 file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
-- linking to entities
-  - <a href="#entity-sub">sub</a>
-  - <a href="#entity-ses">ses</a>
-  - <a href="#entity-task">task</a>
-  - <a href="#entity-acq">acq</a>
-  - - <a href="../04-modality-specific-files/01-magnetic-resonance-imaging-data#entity-acq">fixed link acq</a>
-
-
-
+- [run](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-run-entity)
+- [acq](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-acq-entity)
+- [ce](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-ce-entity)
+- [rec](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-rec-entity)
 
 Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space
 ---                                                                                            | ---           | ---           | ---            | ---           | ---                      | ---            | ---                      | ---           | ---                    | ---            | ---                 | ---                   | ---

From e6f8a59233d144779fae33252b56318cf9781664 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Fri, 12 Jul 2019 17:27:43 +0200
Subject: [PATCH 05/14] some cleanup/clarifying

---
 src/02-common-principles.md                   | 29 ++++++++++---------
 .../01-magnetic-resonance-imaging-data.md     | 26 ++++++++---------
 2 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index a2f29a667c..5da4c5c79b 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -33,15 +33,16 @@ misunderstanding we clarify them here.
     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
+    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), beh (behavioral).
+    (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
-    “resting state” a task. In the context of brain scanning, a task is always
+    "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.
@@ -71,7 +72,7 @@ not covered by this standard. The most sensible place to put it is next to the
 continuous recording file with the same naming scheme but different extensions.
 The solutions will change from case to case and publicly available datasets will
 be reviewed to include common data types in the future releases of the BIDS
-spec.
+specification.
 
 ## Source vs. raw vs. derived data
 
@@ -151,7 +152,7 @@ participant can exist only at participant level directory, i.e
 specific to a participant is to be declared only at top level of dataset for eg:
 `task-sist_bold.json` must be placed under `/dataset/task-sist_bold.json`
 
-Example 1: Two JSON files that are erroneously at the same level.
+Example 1: Two JSON files that are erroneously at the same level
 
 ```Text
 sub-01/
@@ -172,7 +173,7 @@ constraint that no more than one file may be defined at a given level of the
 directory structure. Instead `sub-01_ses-test_task-overtverbgeneration_run-2_bold.json`
 should have been under `sub-01/ses-test/func/`.
 
-Example 2: Multiple run and rec with same acquisition (acq) parameters acq-test1
+Example 2: Multiple `run`s and `rec`s with same acquisition (`acq`) parameters
 
 ```Text
 sub-01/
@@ -191,8 +192,7 @@ apply to different runs and rec files. Also if the JSON file
 (`task-xyz_acq-test1_bold.json`) is defined at dataset top level directory, it
 will be applicable to all task runs with `test1` acquisition parameter.
 
-Example 3: Multiple json files at different levels for same task and
-acquisition parameters
+Example 3: Multiple json files at different levels for same task and acquisition parameters
 
 ```Text
 task-xyz_acq-test1_bold.json
@@ -327,11 +327,14 @@ 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.
+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.
 
 ## Units
 
diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 0177ffd2ee..42e58132e6 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -380,20 +380,18 @@ however the user is free to choose any other label than `singleband` and
 `multiband` as long as they are consistent across subjects and sessions. For
 multiband acquisitions, one can also save the single-band reference image as
 type `sbref` (e.g. `dwi/sub-control01_sbref.nii[.gz]`) The bvec and bval files
-are in the FSL format<sup>4</sup>: The bvec files contain 3 rows with n
-space-delimited floating-point numbers (corresponding to the n volumes in the
-relevant NIfTI file). The first row contains the x elements, the second row
-contains the y elements and third row contains the z elements of a unit vector
-in the direction of the applied diffusion gradient, where the i-th elements in
-each row correspond together to the i-th volume with `[0,0,0]` for
-non-diffusion-weighted volumes. Inherent to the FSL format for bvec
-specification is the fact that the coordinate system of the bvecs is with
-respect to the participant (i.e., defined by the axes of the corresponding
-dwi.nii file) and not the magnet’s coordinate system, which means that any
-rotations applied to dwi.nii also need to be applied to the corresponding bvec
-file.
-
-<sup>4</sup>[http://fsl.fmrib.ox.ac.uk/fsl/fsl4.0/fdt/fdt_dtifit.html](http://fsl.fmrib.ox.ac.uk/fsl/fsl4.0/fdt/fdt_dtifit.html)
+are in the [FSL format](http://fsl.fmrib.ox.ac.uk/fsl/fsl4.0/fdt/fdt_dtifit.html):
+The bvec files contain 3 rows with n space-delimited floating-point numbers
+(corresponding to the n volumes in the relevant NIfTI file). The first row
+contains the x elements, the second row contains the y elements and third row
+contains the z elements of a unit vector in the direction of the applied
+diffusion gradient, where the i-th elements in each row correspond together to
+the i-th volume with `[0,0,0]` for non-diffusion-weighted volumes. Inherent to
+the FSL format for bvec specification is the fact that the coordinate system of
+the bvecs is with respect to the participant (i.e., defined by the axes of the
+corresponding dwi.nii file) and not the magnet’s coordinate system, which means
+that any rotations applied to dwi.nii also need to be applied to the
+corresponding bvec file.
 
 bvec example:
 

From 059e4b195bd8c9768cb811043aa37c876f70381b Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Thu, 25 Jul 2019 14:58:34 +0200
Subject: [PATCH 06/14] fix linter

---
 .../01-magnetic-resonance-imaging-data.md     |  8 ++--
 src/99-appendices/04-entity-table.md          | 48 +++++++++----------
 2 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index 42e58132e6..3dab44ff3b 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -136,7 +136,7 @@ modalities include:
 | Inplane T2         | inplaneT2        | T2-weighted anatomical image matched to functional acquisition                                                                                                                                                                          |
 | Angiography        | angio            |                                                                                                                                                                                                                                         |
 
-###### The `run` entity
+#### 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 integers are allowed as
@@ -144,7 +144,7 @@ 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 `acq` entity
 
 The OPTIONAL `acq-<label>` key/value pair corresponds to a custom label the user
 MAY use to distinguish a different set of parameters used for acquiring the same
@@ -159,14 +159,14 @@ 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
+#### The `ce` entity
 
 Similarly the OPTIONAL `ce-<label>` 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.
 
-###### The `rec` entity
+#### The `rec` entity
 
 Similarly the OPTIONAL `rec-<label>` key/value can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index f68f0339a7..9105ab7c0c 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -7,28 +7,28 @@ precede the reconstruction entity. REQUIRED and OPTIONAL entities for a given
 file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
-- [run](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-run-entity)
-- [acq](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-acq-entity)
-- [ce](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-ce-entity)
-- [rec](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-rec-entity)
+  - [run](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-run-entity)
+  - [acq](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-acq-entity)
+  - [ce](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-ce-entity)
+  - [rec](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-rec-entity)
 
-Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space
----                                                                                            | ---           | ---           | ---            | ---           | ---                      | ---            | ---                      | ---           | ---                    | ---            | ---                 | ---                   | ---
-Format                                                                                         | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>`             | `rec-<label>`  | `dir-<label>`            | `run-<index>` | `mod-<label>`          | `echo-<index>` | `recording-<label>` | `proc-<label>`        | `space-<label>`
-anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               |                        |                |                     |                       |
-anat<br>(defacemask)                                                                           | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               | OPTIONAL               |                |                     |                       |
-func<br>(bold sbref events)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      | OPTIONAL                 | OPTIONAL       | OPTIONAL                 | OPTIONAL      |                        | OPTIONAL       |                     |                       |
-func<br>(physio stim)                                                                          | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          | OPTIONAL       |                          | OPTIONAL      |                        |                | OPTIONAL            | OPTIONAL              |
-dwi<br>(dwi bvec bval)                                                                         | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                | OPTIONAL                 | OPTIONAL      |                        |                |                     |                       |
-fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap)                     | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
-fmap<br>(epi)                                                                                  | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 |                | REQUIRED                 | OPTIONAL      |                        |                |                     |                       |
-beh<br>(events stim physio)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          |               |                        |                |                     |                       |
-meg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     | OPTIONAL              |
-eeg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
-ieeg<br>                                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
-channels<br>(meg/eeg/ieeg)                                                                     | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
-headshape<br>(meg)                                                                             | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
-markers<br>(meg)                                                                               | REQUIRED      | OPTIONAL      | OPTIONAL       | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
-photo<br>(meg/eeg/ieeg)                                                                        | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       |
-electrodes<br>(eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL
-events<br>(meg/eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |
+| Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space           |
+| :--------------------------------------------------------------------------------------------: | :-----------: | :-----------: | :------------: | :-----------: | :----------------------: | :------------: | :----------------------: | :-----------: | :--------------------: | :------------: | :-----------------: | :-------------------: | :---------------|
+| Format                                                                                         | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>`             | `rec-<label>`  | `dir-<label>`            | `run-<index>` | `mod-<label>`          | `echo-<index>` | `recording-<label>` | `proc-<label>`        | `space-<label>` |
+| anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               |                        |                |                     |                       |                 |
+| anat<br>(defacemask)                                                                           | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               | OPTIONAL               |                |                     |                       |                 |
+| func<br>(bold sbref events)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      | OPTIONAL                 | OPTIONAL       | OPTIONAL                 | OPTIONAL      |                        | OPTIONAL       |                     |                       |                 |
+| func<br>(physio stim)                                                                          | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          | OPTIONAL       |                          | OPTIONAL      |                        |                | OPTIONAL            | OPTIONAL              |                 |
+| dwi<br>(dwi bvec bval)                                                                         | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                | OPTIONAL                 | OPTIONAL      |                        |                |                     |                       |                 |
+| fmap<br>(phasediff phase1 phase2 magnitude1 magnitude2 magnitude fieldmap)                     | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |                 |
+| fmap<br>(epi)                                                                                  | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 |                | REQUIRED                 | OPTIONAL      |                        |                |                     |                       |                 |
+| beh<br>(events stim physio)                                                                    | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          |               |                        |                |                     |                       |                 |
+| meg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     | OPTIONAL              |                 |
+| eeg<br>                                                                                        | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |                 |
+| ieeg<br>                                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       | OPTIONAL      |                          |                |                          | OPTIONAL      |                        |                |                     |                       |                 |
+| channels<br>(meg/eeg/ieeg)                                                                     | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |                 |
+| headshape<br>(meg)                                                                             | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL        |
+| markers<br>(meg)                                                                               | REQUIRED      | OPTIONAL      | OPTIONAL       | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL        |
+| photo<br>(meg/eeg/ieeg)                                                                        | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       |                 |        
+| electrodes<br>(eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      |                | OPTIONAL      |                          |                |                          |               |                        |                |                     |                       | OPTIONAL        |
+| events<br>(meg/eeg/ieeg)                                                                       | REQUIRED      | OPTIONAL      | REQUIRED       |               |                          |                |                          | OPTIONAL      |                        |                |                     |                       |                 |        

From 857ed07213d8128e69a8b44796744f4e61b2b191 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Thu, 25 Jul 2019 15:27:05 +0200
Subject: [PATCH 07/14] add general section on entities

---
 src/02-common-principles.md          | 33 ++++++++++++++++++++++++++++
 src/99-appendices/04-entity-table.md |  6 ++---
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 5da4c5c79b..ad77dc913c 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -56,6 +56,39 @@ misunderstanding we clarify them here.
     due to different subject response or randomized nature of the stimuli). Run
     is a synonym of a data acquisition.
 
+## File names consist of key-value pairs (entities)
+
+We define file names with a chain of key-value pairs, each of which we call
+an *entity*. Two prominent examples are the `subject` and `session` entities.
+
+If we want to name a datafile that was collected in a certain `session` from
+a certain `subject`, the name of that datafile will start with the following
+string: `sub-<label>_ses-<label>`.
+
+Note that `sub-<sub-label>` correspondes to the `subject` entity because it has
+the `sub-` "key" and a value `<sub-label>`, where `<sub-label>` would in a real
+datafile correspond to a unique identifier of that subject, such as `01`. The
+same  explanation holds for the `session` entity with its `ses-` key and its
+`<ses-label>` value.
+
+Finally, you can notice how different entities are separated by an underscore
+(`_`).
+
+With this system we can name datafiles in a very human readable way:
+`sub-01_task-rest_eeg.edf`
+
+From the file name alone, a user can tell that the file contains resting state
+data from subject `01`. The *suffix* `_eeg` and the extension `.edf` are
+depending on the imaging modality and the data format and convey further
+information regarding the file's contents.
+
+The list of all entities in BIDS and the order in which they SHOULD be
+specified is available in the [entitiy-table](./99-appendices/04-entity-table.md)
+in the appendix.
+
+Read the relevant sections for the files you want to specify to get a better
+idea on which entities to use and how to use them.
+
 ## 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/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 9105ab7c0c..101204c485 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -7,10 +7,8 @@ precede the reconstruction entity. REQUIRED and OPTIONAL entities for a given
 file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
-  - [run](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-run-entity)
-  - [acq](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-acq-entity)
-  - [ce](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-ce-entity)
-  - [rec](../04-modality-specific-files/01-magnetic-resonance-imaging-data.md#the-rec-entity)
+A general introduction to entities is given in the section on
+[common principles](../02-common-principles.md#file-names-consist-of-key-value-pairs-entities)
 
 | Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space           |
 | :--------------------------------------------------------------------------------------------: | :-----------: | :-----------: | :------------: | :-----------: | :----------------------: | :------------: | :----------------------: | :-----------: | :--------------------: | :------------: | :-----------------: | :-------------------: | :---------------|

From 5bcde1817c0e4b81eacdc70d82b881843f3e7003 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Thu, 25 Jul 2019 15:50:41 +0200
Subject: [PATCH 08/14] right align cells and formtting

---
 src/02-common-principles.md          | 4 ++--
 src/99-appendices/04-entity-table.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index ad77dc913c..36ebdd0ce4 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -66,7 +66,7 @@ a certain `subject`, the name of that datafile will start with the following
 string: `sub-<label>_ses-<label>`.
 
 Note that `sub-<sub-label>` correspondes to the `subject` entity because it has
-the `sub-` "key" and a value `<sub-label>`, where `<sub-label>` would in a real
+the `sub-` "key" and`<sub-label>` "value", where `<sub-label>` would in a real
 datafile correspond to a unique identifier of that subject, such as `01`. The
 same  explanation holds for the `session` entity with its `ses-` key and its
 `<ses-label>` value.
@@ -74,7 +74,7 @@ same  explanation holds for the `session` entity with its `ses-` key and its
 Finally, you can notice how different entities are separated by an underscore
 (`_`).
 
-With this system we can name datafiles in a very human readable way:
+With this system we can name datafiles in a human readable way:
 `sub-01_task-rest_eeg.edf`
 
 From the file name alone, a user can tell that the file contains resting state
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 101204c485..57c81118d9 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -11,7 +11,7 @@ A general introduction to entities is given in the section on
 [common principles](../02-common-principles.md#file-names-consist-of-key-value-pairs-entities)
 
 | Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space           |
-| :--------------------------------------------------------------------------------------------: | :-----------: | :-----------: | :------------: | :-----------: | :----------------------: | :------------: | :----------------------: | :-----------: | :--------------------: | :------------: | :-----------------: | :-------------------: | :---------------|
+| :--------------------------------------------------------------------------------------------- | :------------ | :------------ | :------------- | :------------ | :----------------------- | :------------- | :----------------------- | :------------ | :--------------------- | :------------- | :------------------ | :-------------------- | :---------------|
 | Format                                                                                         | `sub-<label>` | `ses-<label>` | `task-<label>` | `acq-<label>` | `ce-<label>`             | `rec-<label>`  | `dir-<label>`            | `run-<index>` | `mod-<label>`          | `echo-<index>` | `recording-<label>` | `proc-<label>`        | `space-<label>` |
 | anat<br>(T1w T2w T1rho T1map T2map T2star FLAIR FLASH PD PDmap PDT2 inplaneT1 inplaneT2 angio) | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               |                        |                |                     |                       |                 |
 | anat<br>(defacemask)                                                                           | REQUIRED      | OPTIONAL      |                | OPTIONAL      | OPTIONAL                 | OPTIONAL       |                          |               | OPTIONAL               |                |                     |                       |                 |

From 8e2d9e8db4bf3e229b9d7ad62de098c6d606dbe0 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Thu, 25 Jul 2019 20:54:51 +0200
Subject: [PATCH 09/14] Apply suggestions from code review

Co-Authored-By: Chris Markiewicz <effigies@gmail.com>
---
 src/02-common-principles.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 36ebdd0ce4..651a599aa8 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -71,19 +71,18 @@ datafile correspond to a unique identifier of that subject, such as `01`. The
 same  explanation holds for the `session` entity with its `ses-` key and its
 `<ses-label>` value.
 
-Finally, you can notice how different entities are separated by an underscore
-(`_`).
+Note also that entities are separated by an underscore (`_`).
 
 With this system we can name datafiles in a human readable way:
 `sub-01_task-rest_eeg.edf`
 
 From the file name alone, a user can tell that the file contains resting state
-data from subject `01`. The *suffix* `_eeg` and the extension `.edf` are
+data from subject `01`. The *suffix* `_eeg` and the *extension* `.edf` are
 depending on the imaging modality and the data format and convey further
 information regarding the file's contents.
 
 The list of all entities in BIDS and the order in which they SHOULD be
-specified is available in the [entitiy-table](./99-appendices/04-entity-table.md)
+specified is available in the [entity table](./99-appendices/04-entity-table.md)
 in the appendix.
 
 Read the relevant sections for the files you want to specify to get a better

From 472f0fa0ada721173aeb96ae679780e92c49b8e9 Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Thu, 25 Jul 2019 22:22:13 +0200
Subject: [PATCH 10/14] consistent use of <label>

Co-Authored-By: Chris Markiewicz <effigies@gmail.com>
---
 src/02-common-principles.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 651a599aa8..5e5889849c 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -65,11 +65,11 @@ If we want to name a datafile that was collected in a certain `session` from
 a certain `subject`, the name of that datafile will start with the following
 string: `sub-<label>_ses-<label>`.
 
-Note that `sub-<sub-label>` correspondes to the `subject` entity because it has
-the `sub-` "key" and`<sub-label>` "value", where `<sub-label>` would in a real
+Note that `sub-<label>` correspondes to the `subject` entity because it has
+the `sub-` "key" and`<label>` "value", where `<label>` would in a real
 datafile correspond to a unique identifier of that subject, such as `01`. The
 same  explanation holds for the `session` entity with its `ses-` key and its
-`<ses-label>` value.
+`<label>` value.
 
 Note also that entities are separated by an underscore (`_`).
 
@@ -81,7 +81,7 @@ data from subject `01`. The *suffix* `_eeg` and the *extension* `.edf` are
 depending on the imaging modality and the data format and convey further
 information regarding the file's contents.
 
-The list of all entities in BIDS and the order in which they SHOULD be
+The list of all entities in BIDS and the order in which they MUST be
 specified is available in the [entity table](./99-appendices/04-entity-table.md)
 in the appendix.
 

From a6a43564f0eb540f4238a68002ce8ce1856dc2d7 Mon Sep 17 00:00:00 2001
From: "Christopher J. Markiewicz" <markiewicz@stanford.edu>
Date: Fri, 26 Jul 2019 09:30:49 -0400
Subject: [PATCH 11/14] STY: Move to passive voice/imperative mood

---
 src/02-common-principles.md | 40 ++++++++++++++++---------------------
 1 file changed, 17 insertions(+), 23 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 5e5889849c..b5c144b110 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -56,38 +56,32 @@ misunderstanding we clarify them here.
     due to different subject response or randomized nature of the stimuli). Run
     is a synonym of a data acquisition.
 
-## File names consist of key-value pairs (entities)
+## File name structure
 
-We define file names with a chain of key-value pairs, each of which we call
-an *entity*. Two prominent examples are the `subject` and `session` entities.
+File names consist of chains of *entities*, or key-value pairs, a *suffix* and an
+*extension*.
+Two prominent examples of entities are `subject` and `session`.
 
-If we want to name a datafile that was collected in a certain `session` from
-a certain `subject`, the name of that datafile will start with the following
-string: `sub-<label>_ses-<label>`.
+For a data file that was collected in a given `session` from a given
+`subject`, the file name will begin with the string `sub-<label>_ses-<label>`.
 
-Note that `sub-<label>` correspondes to the `subject` entity because it has
-the `sub-` "key" and`<label>` "value", where `<label>` would in a real
-datafile correspond to a unique identifier of that subject, such as `01`. The
-same  explanation holds for the `session` entity with its `ses-` key and its
-`<label>` value.
+Note that `sub-<label>` corresponds to the `subject` entity because it has
+the `sub-` "key" and`<label>` "value", where `<label>` would in a real data file
+correspond to a unique identifier of that subject, such as `01`.
+The same holds for the `session` entity with its `ses-` key and its `<label>`
+value.
 
-Note also that entities are separated by an underscore (`_`).
-
-With this system we can name datafiles in a human readable way:
-`sub-01_task-rest_eeg.edf`
-
-From the file name alone, a user can tell that the file contains resting state
-data from subject `01`. The *suffix* `_eeg` and the *extension* `.edf` are
-depending on the imaging modality and the data format and convey further
-information regarding the file's contents.
+A chain of entities, followed by a suffix, connected by underscores (`_`)
+produces a human readable file name, such as `sub-01_task-rest_eeg.edf`.
+It is evident from the file name alone that the file contains resting state
+data from subject `01`.
+The suffix `eeg` and the extension `.edf` depend on the imaging modality and
+the data format and indicate further details of the file's contents.
 
 The list of all entities in BIDS and the order in which they MUST be
 specified is available in the [entity table](./99-appendices/04-entity-table.md)
 in the appendix.
 
-Read the relevant sections for the files you want to specify to get a better
-idea on which entities to use and how to use them.
-
 ## Compulsory, optional, and additional data and metadata
 
 The following standard describes a way of arranging data and writing down

From dbfe38aa10a9e4ea4e930f712866d43417f8dddc Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Sat, 27 Jul 2019 10:49:01 +0200
Subject: [PATCH 12/14] reorder sections as chris suggested

---
 src/02-common-principles.md | 38 ++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index b5c144b110..1692c5bc30 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -56,6 +56,24 @@ misunderstanding we clarify them here.
     due to different subject response or randomized nature of the stimuli). Run
     is a synonym of a data acquisition.
 
+## Compulsory, optional, and additional data and metadata
+
+The following standard describes a way of arranging data and writing down
+metadata for a subset of neuroimaging experiments. Some aspects of the standard
+are compulsory. For example a particular file name format is required when
+storing structural scans. Some aspects are regulated but optional. For example a
+T2 volume does not need to be included, but when it is available it should be
+saved under a particular file name specified in the standard. This standard
+aspires to describe a majority of datasets, but acknowledges that there will be
+cases that do not fit. In such cases one can include additional files and
+subfolders to the existing folder structure following common sense. For example
+one may want to include eye tracking data in a vendor specific format that is
+not covered by this standard. The most sensible place to put it is next to the
+continuous recording file with the same naming scheme but different extensions.
+The solutions will change from case to case and publicly available datasets will
+be reviewed to include common data types in the future releases of the BIDS
+specification.
+
 ## File name structure
 
 File names consist of chains of *entities*, or key-value pairs, a *suffix* and an
@@ -78,28 +96,10 @@ data from subject `01`.
 The suffix `eeg` and the extension `.edf` depend on the imaging modality and
 the data format and indicate further details of the file's contents.
 
-The list of all entities in BIDS and the order in which they MUST be
+A summary of all entities in BIDS and the order in which they MUST be
 specified is available in the [entity table](./99-appendices/04-entity-table.md)
 in the appendix.
 
-## Compulsory, optional, and additional data and metadata
-
-The following standard describes a way of arranging data and writing down
-metadata for a subset of neuroimaging experiments. Some aspects of the standard
-are compulsory. For example a particular file name format is required when
-storing structural scans. Some aspects are regulated but optional. For example a
-T2 volume does not need to be included, but when it is available it should be
-saved under a particular file name specified in the standard. This standard
-aspires to describe a majority of datasets, but acknowledges that there will be
-cases that do not fit. In such cases one can include additional files and
-subfolders to the existing folder structure following common sense. For example
-one may want to include eye tracking data in a vendor specific format that is
-not covered by this standard. The most sensible place to put it is next to the
-continuous recording file with the same naming scheme but different extensions.
-The solutions will change from case to case and publicly available datasets will
-be reviewed to include common data types in the future releases of the BIDS
-specification.
-
 ## Source vs. raw vs. derived data
 
 BIDS in its current form is designed to harmonize and describe raw (unprocessed

From dc351fa32f20f7a4c3deb2e678669d0cc034e36e Mon Sep 17 00:00:00 2001
From: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
Date: Tue, 30 Jul 2019 10:08:40 +0200
Subject: [PATCH 13/14] Apply suggestions from code review

Co-Authored-By: Chris Markiewicz <effigies@gmail.com>
---
 src/02-common-principles.md          | 2 +-
 src/99-appendices/04-entity-table.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 1692c5bc30..da6c1bb2ed 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -76,7 +76,7 @@ specification.
 
 ## File name structure
 
-File names consist of chains of *entities*, or key-value pairs, a *suffix* and an
+A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
 *extension*.
 Two prominent examples of entities are `subject` and `session`.
 
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 57c81118d9..863f9aad5f 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -8,7 +8,7 @@ file type are denoted. Entity formats indicate whether the value is alphanumeric
 (`<label>`) or numeric (`<index>`).
 
 A general introduction to entities is given in the section on
-[common principles](../02-common-principles.md#file-names-consist-of-key-value-pairs-entities)
+[file name structure](../02-common-principles.md#file-name-structure)
 
 | Entity                                                                                         | Subject       | Session       | Task           | Acquisition   | Contrast Enhancing Agent | Reconstruction | Phase-Encoding Direction | Run           | Corresponding modality | Echo           | Recording           | Processed (on device) | Space           |
 | :--------------------------------------------------------------------------------------------- | :------------ | :------------ | :------------- | :------------ | :----------------------- | :------------- | :----------------------- | :------------ | :--------------------- | :------------- | :------------------ | :-------------------- | :---------------|

From 85eb60e19f7e0f30bf3015db6e8c54b199b9bf51 Mon Sep 17 00:00:00 2001
From: Changelog-bot <franklin.feingold@gmail.com>
Date: Mon, 5 Aug 2019 19:45:53 +0000
Subject: [PATCH 14/14] [DOC] Auto-generate changelog entry for PR #272

---
 src/CHANGES.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/CHANGES.md b/src/CHANGES.md
index b25e59c55f..3b7efd7596 100644
--- a/src/CHANGES.md
+++ b/src/CHANGES.md
@@ -6,6 +6,7 @@ Changelog
 -   \[ENH] Update contributing guide and README to make discussion forums easy to find [#279](https://github.com/bids-standard/bids-specification/pull/279) ([emdupre](https://github.com/emdupre))
 -   \[ENH] Starter Kit dropdown menu [#278](https://github.com/bids-standard/bids-specification/pull/278) ([franklin-feingold](https://github.com/franklin-feingold))
 -   \[INFRA] Update pipenv [#274](https://github.com/bids-standard/bids-specification/pull/274) ([sappelhoff](https://github.com/sappelhoff))
+-   \[INFRA] Transpose the entity table and link to text anchors describing each entity [#272](https://github.com/bids-standard/bids-specification/pull/272) ([sappelhoff](https://github.com/sappelhoff))
 -   \[ENH] Add Twitter badge to README and link to website to landing page [#268](https://github.com/bids-standard/bids-specification/pull/268) ([franklin-feingold](https://github.com/franklin-feingold))
 -   \[ENH] adding release guidelines [#267](https://github.com/bids-standard/bids-specification/pull/267) ([franklin-feingold](https://github.com/franklin-feingold))
 -   \[FIX] Common principles: Fix filename in inheritance principle [#261](https://github.com/bids-standard/bids-specification/pull/261) ([Lestropie](https://github.com/Lestropie))