Merge pull request #442 from sappelhoff/camelsnake

FIX: Clarify  snake_case+CamelCase in TSV+JSON

Author: sappelhoff

src/02-common-principles.md

@@ -264,8 +264,7 @@ additional meta information extracted from DICOM files in a sidecar JSON file
 (with the same filename as the `.nii[.gz]` file, but with a `.json` extension).
 Extraction of BIDS compatible metadata can be performed using [dcm2niix](https://github.com/rordenlab/dcm2niix)
 and [dicm2nii](http://www.mathworks.com/matlabcentral/fileexchange/42997-dicom-to-nifti-converter/content/dicm2nii.m)
-DICOM to NIfTI converters. A provided
-[validator](https://github.com/bids-standard/bids-validator)
+DICOM to NIfTI converters. The [BIDS-validator](https://github.com/bids-standard/bids-validator)
 will check for conflicts between the JSON file and the data recorded in the
 NIfTI header.
 
@@ -274,9 +273,13 @@ NIfTI header.
 Tabular data MUST be saved as tab delimited values (`.tsv`) files, i.e., CSV
 files where commas are replaced by tabs. Tabs MUST be true tab characters and
 MUST NOT be a series of space characters. Each TSV file MUST start with a header
-line listing the names of all columns (with the exception of physiological and
-other continuous acquisition data - see below for details). Names MUST be
-separated with tabs. String values containing tabs MUST be escaped using double
+line listing the names of all columns (with the exception of
+[physiological and other continuous recordings](04-modality-specific-files/06-physiological-and-other-continuous-recordings.md)).
+Names MUST be separated with tabs.
+It is RECOMMENDED that the column names in the header of the TSV file are
+written in [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) with the
+first letter in lower case (e.g., `variable_name`, not `Variable_name`).
+String values containing tabs MUST be escaped using double
 quotes. Missing and non-applicable values MUST be coded as `n/a`. Numerical
 values MUST employ the dot (`.`) as decimal separator and MAY be specified
 in scientific notation, using `e` or `E` to separate the significand from the
@@ -340,8 +343,14 @@ format can be found here: [http://json.org/](http://json.org/). Several editors
 have built-in support for JSON syntax highlighting that aids manual creation of
 such files. An online editor for JSON with built-in validation is available at:
 [http://jsoneditoronline.org](http://jsoneditoronline.org). 
+It is RECOMMENDED that keys in a JSON file are written in [CamelCase](https://en.wikipedia.org/wiki/Camel_case)
+with the first letter in upper case (e.g., `SamplingFrequency`, not
+`samplingFrequency`). Note however, when a JSON file is used as an accompanying
+sidecar file for a [TSV file](#tabular-files), the keys linking a TSV column
+with their description in the JSON file need to follow the exact formatting
+as in the TSV file.
 
-Example:
+Example of a hypothetical `*_bold.json` file, accompanying a `*_bold.nii` file:
 
 ```JSON
 {
@@ -350,6 +359,23 @@ Example:
 }
 ```
 
+Example of a hypothetical `*_events.json` file, accompanying an
+`*_events.tsv` file. Note that the JSON file contains a key describing an
+*arbitrary* column `stim_presentation_side` in the TSV file it accompanies.
+See [task events section](04-modality-specific-files/05-task-events.md)
+for more information.
+
+```JSON
+{
+  "stim_presentation_side": {
+    "Levels": {
+      "1": "stimulus presented on LEFT side",
+      "2": "stimulus presented on RIGHT side"
+    }
+  }
+}
+```
+
 ## Participant names and other labels
 
 BIDS uses custom user-defined labels in several situations (naming of

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

@@ -102,9 +102,10 @@ Useful for multimodal co-registration with MEG, (S)EEG, TMS, etc.
 | InstitutionAddress          | RECOMMENDED. The address of the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0081 `InstitutionAddress`.               |
 | InstitutionalDepartmentName | RECOMMENDED. The department in the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1040 `Institutional Department Name`. |
 
-When adding additional metadata please use the camelcase version of
+When adding additional metadata please use the CamelCase version of
 [DICOM ontology terms](https://scicrunch.org/scicrunch/interlex/dashboard)
-whenever possible.
+whenever possible. See also
+[recommendations on JSON files](../02-common-principles.md#keyvalue-files-dictionaries).
 
 ### Anatomy imaging data
 

src/04-modality-specific-files/05-task-events.md

@@ -45,7 +45,8 @@ the first volume.
 
 An arbitrary number of additional columns can be added. Those allow describing
 other properties of events that could be later referred in modelling and
-hypothesis extensions of BIDS.
+hypothesis extensions of BIDS. Note that any additional columns in a TSV file
+SHOULD be documented in an accompanying JSON sidecar file.
 
 In case of multi-echo task run, a single `_events.tsv` file will suffice for all
 echoes.