Merge remote-tracking branch 'origin/master' into bf-links-docker

* origin/master:
  [DOC] Auto-generate changelog entry for PR #272
  Apply suggestions from code review
  reorder sections as chris suggested
  STY: Move to passive voice/imperative mood
  consistent use of <label>
  Apply suggestions from code review
  right align cells and formtting
  add general section on entities
  fix linter
  some cleanup/clarifying
  try links via tiny headings
  try fix links
  try links
  transpose entity table

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,33 @@ 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.
+
+## File name structure
+
+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`.
+
+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>` 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.
+
+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.
+
+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.
 
 ## Source vs. raw vs. derived data
 
@@ -151,7 +178,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 +199,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 +218,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 +353,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
 

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

@@ -136,12 +136,16 @@ 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 `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 -
@@ -155,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).
 
@@ -372,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>[https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT)
+are in the [FSL format](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT/UserGuide#DTIFIT):
+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: