Merge pull request #1440 from yarikoptic/rf-events

[ENH] Remove explicitly worded requirement of events file association with the task, move events to modality-agnostic portion of the specifications.

Author: neuromechanist

mkdocs.yml

@@ -10,12 +10,12 @@ nav:
           - Data summary files: modality-agnostic-files/data-summary-files.md
           - Phenotypic and assessment data: modality-agnostic-files/phenotypic-and-assessment-data.md
           - Code: modality-agnostic-files/code.md
+          - Events: modality-agnostic-files/events.md
       - Modality specific files:
           - Magnetic Resonance Imaging: modality-specific-files/magnetic-resonance-imaging-data.md
           - Magnetoencephalography: modality-specific-files/magnetoencephalography.md
           - Electroencephalography: modality-specific-files/electroencephalography.md
           - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md
-          - Task events: modality-specific-files/task-events.md
           - Physiological recordings: modality-specific-files/physiological-recordings.md
           - Behavioral experiments (with no neural recordings): modality-specific-files/behavioral-experiments.md
           - Genetic Descriptor: modality-specific-files/genetic-descriptor.md
@@ -142,7 +142,7 @@ plugins:
         "04-modality-specific-files/02-magnetoencephalography.md": "modality-specific-files/magnetoencephalography.md"
         "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md"
         "04-modality-specific-files/04-intracranial-electroencephalography.md": "modality-specific-files/intracranial-electroencephalography.md"
-        "04-modality-specific-files/05-task-events.md": "modality-specific-files/task-events.md"
+        "04-modality-specific-files/05-task-events.md": "modality-agnostic-files/events.md"
         "04-modality-specific-files/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-recordings.md"
         "04-modality-specific-files/07-behavioral-experiments.md": "modality-specific-files/behavioral-experiments.md"
         "04-modality-specific-files/08-genetic-descriptor.md": "modality-specific-files/genetic-descriptor.md"
@@ -168,5 +168,6 @@ plugins:
         "99-appendices/11-qmri.md": "appendices/qmri.md"
         "99-appendices/12-arterial-spin-labeling.md": "appendices/arterial-spin-labeling.md"
         "99-appendices/13-cross-modality-correspondence.md": "appendices/cross-modality-correspondence.md"
+        "modality-specific-files/task-events.md": "modality-agnostic-files/events.md"
 docs_dir: "src"
 use_directory_urls: false

src/CHANGES.md

@@ -602,7 +602,7 @@
 
 -   Added support for MEG data (merged BEP008).
 -   Added `SequenceName` field.
--   Added support for describing events with Hierarchical Event Descriptors: [4.3 Task events](modality-specific-files/task-events.md).
+-   Added support for describing events with Hierarchical Event Descriptors: [4.3 Task events](modality-agnostic-files/events.md).
 -   Added `VolumeTiming` and `AcquisitionDuration` fields: [4.1 Task (including resting state) imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#task-including-resting-state-imaging-data).
 -   Added `DwellTime` field.
 

src/appendices/hed.md

@@ -34,7 +34,7 @@ on GitHub.
 
 Event-related data in BIDS appears in tab-separated value (`events.tsv`)
 files in various places in the dataset hierarchy
-(see [Events](../modality-specific-files/task-events.md)).
+(see [Events](../modality-agnostic-files/events.md)).
 
 `events.tsv` files MUST have `onset` and `duration` columns.
 Dataset curators MAY also include additional columns and define their

src/common-principles.md

@@ -677,7 +677,7 @@ Example of a hypothetical `*_bold.json` file, accompanying a `*_bold.nii` file:
 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](modality-specific-files/task-events.md)
+See [events section](modality-agnostic-files/events.md)
 for more information.
 
 ```JSON

src/modality-specific-files/task-events.md renamed to src/modality-agnostic-files/events.md

@@ -1,12 +1,14 @@
-# Task events
+# Events
 
 The purpose of this file is to describe timing and other properties of events
-recorded during a run.
-Events are, for example, stimuli presented to the participant or participant responses
-(see [Definitions](../common-principles.md#definitions)).
+recorded during data acquisition.
+Events may include stimuli presented to the participant, participant responses
+that are associated with tasks, or markers of other incidents that occurred
+during the execution of the experiment.
+See the [definition of Event](../common-principles.md#definitions) for a more detailed explanation.
 A single event file MAY include any combination of stimulus, response, and other events.
 Events MAY overlap in time.
-Please mind that this does not imply that only so called "event related" study designs
+Please keep in 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).
@@ -18,10 +20,10 @@ duration).
    )
 }}
 
-Each task events file REQUIRES a corresponding task data file.
-It is also possible to have a single `events.tsv` file describing events
-for all participants and runs (see
-[Inheritance Principle](../common-principles.md#the-inheritance-principle)).
+Each `events.tsv` file REQUIRES at least one corresponding data file.
+Through the [Inheritance Principle](../common-principles.md#the-inheritance-principle),
+a single `events.tsv` file MAY describe events for multiple participants,
+sessions, and runs.
 As with all other tabular data, `events.tsv` files MAY be accompanied
 by a JSON file describing the columns in detail
 (see [Tabular Files](../common-principles.md#tabular-files)).
@@ -35,7 +37,7 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_columns_table("task.TaskEvents") }}
+{{ MACROS___make_columns_table("events.Events") }}
 
 The content of  `events.tsv` files SHOULD be sorted by values in the `onset` column.
 
@@ -59,7 +61,7 @@ SHOULD be documented in an accompanying JSON sidecar file.
     if any acquired scans have been discarded before forming the imaging data file,
     ensure that an `onset` of 0 corresponds to the time the first image was stored.
     For example in case there is an in scanner training phase that
-    begins before the scanning sequence has started events from this sequence should
+    begins before the scanning sequence has started, events from this sequence should
     have negative onset time counting down to the beginning of the acquisition of
     the first volume.
 

src/modality-specific-files/behavioral-experiments.md

@@ -38,7 +38,7 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_columns_table("task.Behavioral") }}
+{{ MACROS___make_columns_table("events.Behavioral") }}
 
 ## Sidecar JSON (`*_beh.json`)
 

src/modality-specific-files/positron-emission-tomography.md

@@ -83,7 +83,7 @@ Volumes MUST be stored in chronological order (the order they were acquired in).
 The OPTIONAL [`task-<label>`](../appendices/entities.md#task) is used to
 indicate a task subjects were asked to perform in the scanner.
 Those labels MUST be consistent across subjects and sessions.
-For task based PET, a corresponding [`task events`](./task-events.md) file MUST be provided
+For task based PET, a corresponding [`events`](../modality-agnostic-files/events.md) file MUST be provided
 (please note that this file is not necessary for resting scans).
 
 The [`trc-<label>`](../appendices/entities.md#trc) entity is used to

src/pregh-changes.md

@@ -9,7 +9,7 @@
 
 -   Added support for MEG data (merged BEP008).
 -   Added `SequenceName` field.
--   Added support for describing events with Hierarchical Event Descriptors: [4.3 Task events](modality-specific-files/task-events.md).
+-   Added support for describing events with Hierarchical Event Descriptors: [4.3 Events](modality-agnostic-files/events.md).
 -   Added `VolumeTiming` and `AcquisitionDuration` fields: [4.1 Task (including resting state) imaging data](modality-specific-files/magnetic-resonance-imaging-data.md#task-including-resting-state-imaging-data).
 -   Added `DwellTime` field.
 

src/schema/objects/columns.yaml

@@ -1,9 +1,9 @@
 ---
 HED:
   name: HED
-  display_name: HED Tag
+  display_name: HED
   description: |
-    Hierarchical Event Descriptor (HED) Tag.
+    Hierarchical Event Descriptor (HED) tags.
     See the [HED Appendix](SPEC_ROOT/appendices/hed.md) for details.
   type: string
 abbreviation:
@@ -582,7 +582,7 @@ stim_file:
     Represents the location of the stimulus file (such as an image, video, or
     audio file) presented at the given onset time.
     There are no restrictions on the file formats of the stimuli files,
-    but they should be stored in the `/stimuli` directory
+    but they should be stored in the `/stimuli/` directory
     (under the root directory of the dataset; with optional subdirectories).
     The values under the `stim_file` column correspond to a path relative to
     `/stimuli`.

src/schema/objects/entities.yaml

@@ -418,7 +418,7 @@ task:
     The `task-<label>` MUST be consistent across subjects and sessions.
 
     Files with the `task-<label>` entity SHOULD have an associated
-    [events file](SPEC_ROOT/modality-specific-files/task-events.md#task-events),
+    [events file](SPEC_ROOT/modality-agnostic-files/events.md#events),
     as well as certain metadata fields in the associated JSON file.
 
     For the purpose of this specification we consider the so-called "resting state" a task,