[ENH] add optional presentation software name, version, OS, and code to events.json

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

@@ -10,25 +10,31 @@ sub-<label>/[ses-<label>]
 ```
 
 Where `<matches>` corresponds to task file name. For example:
-`sub-control01_task-nback`. It is also possible to have a single \_events.tsv
-file describing events for all participants and runs (see [Inheritance Principle](../02-common-principles.md#the-inheritance-principle)).
-As with all other tabular data, `_events` files may be
-accompanied by a JSON file describing the columns in detail (see [here](../02-common-principles.md#tabular-files)).
+`sub-control01_task-nback`.
+It is also possible to have a single `_events.tsv` file describing events
+for all participants and runs (see
+[Inheritance Principle](../02-common-principles.md#the-inheritance-principle)).
+As with all other tabular data, `_events.tsv` files MAY be accompanied by a JSON
+file describing the columns in detail (see
+[Tabular Files](../02-common-principles.md#tabular-files)).
 
 The purpose of this file is to describe timing and other properties of events
-recorded during the scan. Events MAY be either stimuli presented to the
-participant or participant responses. A single event file MAY include any
-combination of stimuli and response events. Events MAY overlap in time. Please
-mind that this does not imply that only so called "event related" study designs
+recorded during the scan.
+Events MAY be either stimuli presented to the participant or participant responses.
+A single event file MAY include any combination of stimuli and response events.
+Events MAY overlap in time.
+Please mind that this does not imply that only so called "event related" study designs
 are supported (in contrast to "block" designs) - each "block of events" can be
 represented by an individual row in the \_events.tsv file (with a long
-duration). Each task events file REQUIRES a corresponding task imaging data file
+duration).
+Each task events file REQUIRES a corresponding task imaging data file
 (but a single events file MAY be shared by multiple imaging data files - see
-Inheritance principle). The tabular files consists of one row per event and a set of
-REQUIRED and OPTIONAL columns:
+[Inheritance Principle](../02-common-principles.md#the-inheritance-principle)).
+The tabular files consists of one row per event and a set of REQUIRED
+and OPTIONAL columns:
 
 | Column name   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | onset         | REQUIRED. Onset (in seconds) of the event measured from the beginning of the acquisition of the first volume in the corresponding task imaging data file. If any acquired scans have been discarded before forming the imaging data file, ensure that a time of 0 corresponds to the first image stored. In other words negative numbers in "onset" are allowed<sup>5</sup>.                                                                                                     |
 | duration      | REQUIRED. Duration of the event (measured from onset) in seconds. Must always be either zero or positive. A "duration" value of zero implies that the delta function or event is so short as to be effectively modeled as an impulse.                                                                                                                                                                                                                                            |
 | sample        | OPTIONAL. Onset of the event according to the sampling scheme of the recorded modality (i.e., referring to the raw data file that the `events.tsv` file accompanies).                                                                                                                                                                                                                                                                                                            |
@@ -45,21 +51,21 @@ 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.  
-Note that the `trial_type` and 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.
+hypothesis extensions of BIDS.
+Note that the `trial_type` and any additional columns in a TSV file
+SHOULD be documented in an accompanying JSON sidecar file.
 
 Example:
 
 ```Text
 sub-control01/
     func/
         sub-control01_task-stopsignal_events.tsv
+        sub-control01_task-stopsignal_events.json
 ```
 
+Example of the content of the TSV file:
+
 ```Text
 onset duration  trial_type  response_time stim_file
 1.2 0.6 go  1.435 images/red_square.jpg
@@ -79,7 +85,22 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows:
        }
     }
 }
-```	   
+```
+
+Note that all other columns SHOULD also be described but are omitted for the
+sake of brevity.
+
+For multi-echo files, the `*_events.tsv` file is applicable to all echos of
+a particular run:
+
+```Text
+sub-01_task-cuedSGT_run-1_events.tsv
+sub-01_task-cuedSGT_run-1_echo-1_bold.nii.gz
+sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz
+sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz
+```
+
+## Stimuli databases
 
 References to existing databases can also be encoded using additional columns.
 Example 2 includes references to the Karolinska Directed Emotional Faces (KDEF)
@@ -93,29 +114,76 @@ Example:
 sub-control01/
     func/
         sub-control01_task-emoface_events.tsv
+        sub-control01_task-emoface_events.json
 ```
 
+Example of the content of the TSV file:
+
 ```Text
 onset duration  trial_type  identifier  database  response_time
 1.2 0.6 afraid  AF01AFAF  kdef  1.435
 5.6 0.6 angry AM01AFAN  kdef  1.739
 5.6 0.6 sad AF01ANSA  kdef  1.739
 ```
 
-This file should be accompanied by a data dictionary.  
+The `trial_type` and `identifier` columns from the `*_events.tsv` files might be described
+in the accompanying JSON sidecar as follows:
 
-```Text
-sub-control01/
-    func/
-        sub-control01_task-emoface_events.json
+```JSON
+{
+   "trial_type": {
+       "LongName": "Emotion image type",
+       "Descripton": "Type of emotional face from Karolinska database that is displayed",
+       "Levels": {
+          "afraid": "A face showing fear is displayed",
+          "angry": "A face showing anger is displayed",
+          "sad": "A face showing sadness is displayed"
+        }
+   },
+   "identifier": {
+       "LongName": "Karolinska (KDEF) database identifier",
+       "Description": "ID from KDEF database used to identify the displayed image"
+   }
+}
 ```
 
-The `trial_type` and `identifier` columns from the `*_events.tsv` files might be described in this
-dictionary as follows. 
-Note that all other columns SHOULD also be described but are omitted for the sake
-of example.
+Note that all other columns SHOULD also be described but are omitted for the
+sake of brevity.
+
+## Stimulus presentation details
+
+It is RECOMMENDED to include details of the stimulus presentation software,
+when applicable:
+
+| Field name           | Description                                                                                                                                                                                                                                                        |
+|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| StimulusPresentation | RECOMMENDED. [Object][] containing key value pairs related to the software used to present the stimuli during the experiment, specifically: `OperatingSystem`, `SoftwareName`, `SoftwareRRID`, `SoftwareVersion` and `Code`. See table below for more information. |
+
+The object supplied for `StimulusPresentation` SHOULD include the following key-value pairs:
+
+| Key name        | Description                                                                                                                                                                                                                   |
+|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| OperatingSystem | RECOMMENDED. Operating system used to run the stimuli presentation software (for formatting recommendations, see examples below this table).                                                                                  |
+| SoftwareName    | RECOMMENDED. Name of the software that was used to present the stimuli.                                                                                                                                                       |
+| SoftwareRRID    | RECOMMENDED. [Research Resource Identifier](https://scicrunch.org/resources) of the software that was used to present the stimuli. Examples: The RRID for Psychtoolbox is 'SCR_002881', and that of PsychoPy is 'SCR_006571'. |
+| SoftwareVersion | RECOMMENDED. Version of the software that was used to present the stimuli.                                                                                                                                                    |
+| Code            | RECOMMENDED. [URI][uri] of the code used to present the stimuli. Persistent identifiers such as DOIs are preferred. If multiple versions of code may be hosted at the same location, revision-specific URIs are recommended.  |
+
+The operating system description should include:
+-   type (Windows, MacOS, Linux),
+-   distribution (if applicable: Ubuntu, Debian)
+-   the version number or equivalent code name
+
+Examples:
+-   Windows - 10
+-   macOS - Catalina or macOS - 10.15
+-   Linux - Ubuntu - Bionic Beaver
+-   Linux - Ubuntu - 18.04.5 LTS
 
-```JSON  
+The information related to stimulus presentation might be described
+in the accompanying JSON sidecar as follows (based on the example of the previous section):
+
+```JSON
 {
    "trial_type": {
        "LongName":   "Emotion image type",
@@ -129,16 +197,18 @@ of example.
    "identifier": {
        "LongName": "Unique identifier from Karolinska (KDEF) database",
        "Description": "ID from KDEF database used to identify the displayed image"
-   }
+   },
+    "StimulusPresentation": {
+        "OperatingSystem": "Linux-Ubuntu 18.04.5 LTS",
+        "SoftwareName": "Psychtoolbox",
+        "SoftwareRRID": "SCR_002881",
+        "SoftwareVersion": "3.0.14",
+        "Code": "doi:10.5281/zenodo.3361717"
+    }
 }
-```	   
+```
 
-For multi-echo files, the `*_events.tsv` file is applicable to all echos of particular
-run:
+<!-- Link Definitions -->
 
-```Text
-sub-01_task-cuedSGT_run-1_events.tsv
-sub-01_task-cuedSGT_run-1_echo-1_bold.nii.gz
-sub-01_task-cuedSGT_run-1_echo-2_bold.nii.gz
-sub-01_task-cuedSGT_run-1_echo-3_bold.nii.gz
-```
+[object]: https://www.json.org/json-en.html
+[uri]: https://github.com/bids-standard/bids-starter-kit/wiki/Glossary#uri