From 223deae97d23886156c4a2b5e843116459e96b1e Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Thu, 21 Mar 2024 11:11:24 -0400 Subject: [PATCH] update task and beh pages --- .../behavioral-experiments.md | 27 ++++-- src/modality-specific-files/task-events.md | 84 ++++++++++--------- 2 files changed, 62 insertions(+), 49 deletions(-) diff --git a/src/modality-specific-files/behavioral-experiments.md b/src/modality-specific-files/behavioral-experiments.md index aa17cc3757..a7a979204c 100644 --- a/src/modality-specific-files/behavioral-experiments.md +++ b/src/modality-specific-files/behavioral-experiments.md @@ -1,5 +1,11 @@ # Behavioral experiments (with no neural recordings) +!!! example "Example datasets" + + Datasets containing behavioral data can be found + in the [BIDS examples repository](https://bids-standard.github.io/bids-examples/#behavioral) + and can be used as helpful guidance when curating new datasets. + {{ MACROS___make_filename_template("raw", datatypes=["beh"]) }} -In addition to logs from behavioral experiments performed alongside imaging data -acquisitions, one can also include data from experiments performed with no neural -recordings. -The results of those experiments can be stored in the `beh` directory using the same -formats for event timing (`_events.tsv`), metadata (`_events.json`), +In addition to logs from behavioral experiments +performed alongside imaging data acquisitions, +one MAY also include data from experiments +performed with no neural recordings. +The results of those experiments MAY be stored in the `beh` directory +using the same formats for event timing (`_events.tsv`), +metadata (`_events.json`), physiological (`_physio.tsv.gz`, `_physio.json`) and other continuous recordings (`_stim.tsv.gz`, `_stim.json`) as for tasks performed during MRI, electrophysiological or other neural recordings. -Additionally, events files that do not include the mandatory `onset` and -`duration` columns can still be included, but should be labeled `_beh.tsv` -rather than `_events.tsv`. +Additionally, events files +that do not include the mandatory `onset` and `duration` columns +MAY be included, +but SHOULD be labeled `_beh.tsv` rather than `_events.tsv`. ## Sidecar JSON (`*_beh.json`) @@ -30,7 +39,7 @@ In addition to the metadata that is either: - REQUIRED for some data that can be found in the `beh` directory (for example `SamplingFrequency` and `StartTime` for `*_.tsv.gz` files), -it is RECOMMENDED to add the following metadata to the JSON files of this directory. +It is RECOMMENDED to add the following metadata to the JSON files of this directory. ### Task information diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index 0fb6ec2a52..f6eceb0e29 100644 --- a/src/modality-specific-files/task-events.md +++ b/src/modality-specific-files/task-events.md @@ -27,9 +27,9 @@ 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)). -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)). +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)). The tabular files consists of one row per event and a set of REQUIRED and OPTIONAL columns: @@ -42,22 +42,26 @@ and a guide for using macros can be found at --> {{ MACROS___make_columns_table("task.TaskEvents") }} -Note for MRI data: -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 -have negative onset time counting down to the beginning of the acquisition of -the first volume. - -Note regarding the precision of numeric metadata: -It is RECOMMENDENDED that dataset curators specify numeric metadata like `onset` and -`duration` with as much decimal precision as is reasonable in the context of the experiment. -For example in an EEG experiment with devices operating at 1000 Hz sampling frequency, -dataset curators SHOULD specify **at least** 3 figures after the decimal point. - -An arbitrary number of additional columns can be added. Those allow describing -other properties of events that could be later referenced in modeling and +!!! note "For fMRI data" + + For fMRI data + 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 + have negative onset time counting down to the beginning of the acquisition of + the first volume. + +!!! note "Regarding the precision of numeric metadata" + + For the precision of numeric metadata, + it is RECOMMENDENDED that dataset curators specify numeric metadata like `onset` and + `duration` with as much decimal precision as is reasonable in the context of the experiment. + For example in an EEG experiment with devices operating at 1000 Hz sampling frequency, + dataset curators SHOULD specify **at least** 3 figures after the decimal point. + +An arbitrary number of additional columns can be added. +Those allow describing other properties of events that could be later referenced in modeling 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. @@ -117,24 +121,26 @@ In the accompanying JSON sidecar, the `trial_type` column might look as follows: } ``` -Note that in the example above: +!!! note -1. Only a subset of columns are described for the sake of brevity. - In a real dataset, all other columns SHOULD also be described. + In the example above: -1. The `channel` column contains a list of values that are separated - by a delimiter (`|`), as is declared in the `Delimiter` metadata - field of the `events.json file. - Thus, the channels related to the event in the third row of the example - are called `F,1`, `F,2`, and `Cz`. + 1. Only a subset of columns are described for the sake of brevity. + In a real dataset, all other columns SHOULD also be described. -1. The example contains a column called `annots`. - This column is not defined in BIDS, and constitutes additional, arbitrary - (that is, unofficial) metadata. - In the present case, it is used to describe artifacts in the data, - in reference to the `channel` column. - The `annots` column is making - use of the powerful HED system for documenting events, see below. + 1. The `channel` column contains a list of values that are separated + by a delimiter (`|`), as is declared in the `Delimiter` metadata + field of the `events.json file. + Thus, the channels related to the event in the third row of the example + are called `F,1`, `F,2`, and `Cz`. + + 1. The example contains a column called `annots`. + This column is not defined in BIDS, and constitutes additional, arbitrary + (that is, unofficial) metadata. + In the present case, it is used to describe artifacts in the data, + in reference to the `channel` column. + The `annots` column is making + use of the powerful HED system for documenting events, see below. Events MAY also be documented in machine-actionable form using HED (Hierarchical Event Descriptor) tags. @@ -143,8 +149,8 @@ in event-related analyses. See [Hierarchical Event Descriptors](../appendices/hed.md) for additional information and examples. -For multi-echo files, the `events.tsv` file is applicable to all echos of -a particular run: +For multi-echo files, the `events.tsv` file is applicable +to all echos of a particular run: