diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 0e66a45f93..45a990a58c 100644 --- a/src/02-common-principles.md +++ b/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 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 5e652f866b..e29f050d64 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 @@ -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 diff --git a/src/04-modality-specific-files/05-task-events.md b/src/04-modality-specific-files/05-task-events.md index 99df84d406..01bdec5fa8 100644 --- a/src/04-modality-specific-files/05-task-events.md +++ b/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.