diff --git a/mkdocs.yml b/mkdocs.yml index 051aa2aaa6..114e05c135 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,7 +12,7 @@ nav: - Electroencephalography: modality-specific-files/electroencephalography.md - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md - Task events: modality-specific-files/task-events.md - - Physiological and other continuous recordings: modality-specific-files/physiological-and-other-continuous-recordings.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 - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md @@ -122,7 +122,7 @@ plugins: "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/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-and-other-continuous-recordings.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" "04-modality-specific-files/09-positron-emission-tomography.md": "modality-specific-files/positron-emission-tomography.md" diff --git a/src/modality-specific-files/physiological-and-other-continuous-recordings.md b/src/modality-specific-files/physiological-recordings.md similarity index 84% rename from src/modality-specific-files/physiological-and-other-continuous-recordings.md rename to src/modality-specific-files/physiological-recordings.md index 8ecd00febe..897deb3d1b 100644 --- a/src/modality-specific-files/physiological-and-other-continuous-recordings.md +++ b/src/modality-specific-files/physiological-recordings.md @@ -1,11 +1,8 @@ -# Physiological and other continuous recordings +# Physiological recordings -## Physiological recordings - -Physiological recordings such as cardiac and respiratory signals and other -continuous measures (such as parameters of a film or audio stimuli) MAY be +Physiological recordings such as cardiac and respiratory signals MAY be specified using a [compressed tabular file](../common-principles.md#compressed-tabular-files) -([TSVGZ file](../glossary.md#tsvgz-extensions)) and a corresponding +([TSV.GZ file](../glossary.md#tsvgz-extensions)) and a corresponding JSON file for storing metadata fields (see below). !!! example "Example datasets" @@ -24,8 +21,6 @@ sub-<label>/[ses-<label>/] <datatype>/ <matches>[_recording-<label>]_physio.tsv.gz <matches>[_recording-<label>]_physio.json - <matches>[_recording-<label>]_stim.tsv.gz - <matches>[_recording-<label>]_stim.json ``` For the template directory name, `<datatype>` can correspond to any data @@ -37,12 +32,12 @@ before the suffix. For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`, `<matches>` would correspond to `sub-control01_task-nback_run-1`. -!!! note "TSVGZ headers are specified in metadata files." +!!! warning "Caution" - TSVGZ files MUST NOT include a header line, - as established by the [common-principles](../common-principles.md#compressed-tabular-files). - As a result, when supplying a `*_<physio|stim>.tsv.gz` file, an accompanying - `*_<physio|stim>.json` MUST be supplied as well. + `<matches>_physio.tsv.gz` files MUST NOT include a header line, as established by the + [common-principles](../common-principles.md#compressed-tabular-files). + As a result, when supplying a `<matches>_physio.tsv.gz` file, an accompanying + `<matches>_physio.json` MUST be present to indicate the column names. The [`recording-<label>`](../appendices/entities.md#recording) entity MAY be used to distinguish between several recording files. @@ -51,10 +46,9 @@ the eyetracking data in a certain sampling frequency, and `sub-01_task-bart_recording-breathing_physio.tsv.gz` to contain respiratory measurements in a different sampling frequency. -Physiological recordings (including eyetracking) SHOULD use the `_physio` -suffix, and signals related to the stimulus SHOULD use `_stim` suffix. +Physiological recordings (including eyetracking) MUST use the `_physio` suffix. -The following tables specify metadata fields for the `*_<physio|stim>.json` file. +The following tables specify metadata fields for the `*_physio.json` file. <!-- This block generates a metadata table. These tables are defined in @@ -174,13 +168,8 @@ stored in separate files (and the [`recording-<label>`](../appendices/entities.md#recording) entity MAY be used to distinguish these files). -If the same continuous recording has been used for all subjects (for example in -the case where they all watched the same movie), one file MAY be used and -placed in the root directory. -For example, `task-movie_stim.tsv.gz` - For motion parameters acquired from MRI scanner side motion correction, the -`_physio` suffix SHOULD be used. +`_physio` suffix MUST be used. For multi-echo data, a given `physio.tsv` file is applicable to all echos of a particular run. diff --git a/src/modality-specific-files/task-events.md b/src/modality-specific-files/task-events.md index 9b0ffa69f3..c3822094a5 100644 --- a/src/modality-specific-files/task-events.md +++ b/src/modality-specific-files/task-events.md @@ -126,7 +126,7 @@ Note that 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. + 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`. @@ -311,3 +311,88 @@ in the accompanying JSON sidecar as follows (based on the example of the previou "VisionCorrection": "lenses" } ``` + +### Continuously-sampled, stimulus-related signals + +!!! example "Example datasets" + + The following [BIDS-Examples](https://bids-standard.github.io/bids-examples/#dataset-index) + showcase stimulus-related signals and may be used as a reference + when curating a new dataset: + + - ["synthetic" example dataset](https://github.com/bids-standard/bids-examples/tree/master/synthetic). + +Signals related to stimuli (such as parameters of a film or audio stimuli) that are +evenly recorded at a constant sampling frequency MUST be specified using a +[compressed tabular file](../common-principles.md#compressed-tabular-files) +([TSV.GZ file](../glossary.md#tsvgz-extensions)) and a corresponding +JSON file for storing metadata fields (see below). + +Template: + +```Text +sub-<label>/[ses-<label>/] + <datatype>/ + <matches>_stim.tsv.gz + <matches>_stim.json +``` + +For the template directory name, `<datatype>` can correspond to any data +recording modality. + +In the template filenames, the `<matches>` part corresponds to task filename +before the suffix. +For example for the file `sub-control01_task-nback_run-1_bold.nii.gz`, +`<matches>` would correspond to `sub-control01_task-nback_run-1`. + +!!! warning "Caution" + + `<matches>_stim.tsv.gz` files MUST NOT include a header line, + as established by the [common-principles](../common-principles.md#compressed-tabular-files). + As a result, when supplying a `<matches>_stim.tsv.gz` file, an accompanying + `<matches>_stim.json` MUST be present to indicate the column names. + +If the same continuous recording has been used for all subjects (for example in +the case where they all watched the same movie), one file placed in the +root directory (for example, `<root>/task-movie_stim.<tsv.gz|json>`) MAY be used +and will apply to all `<matches>_task-movie_<matches>_<suffix>.<ext>` files. +In the following example, the two `task-nback_stim.<json|tsv.gz>` apply +to all the `task-nback` runs across the two available subjects: + +<!-- This block generates a file tree. +A guide for using macros can be found at + https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md +--> +{{ MACROS___make_filetree_example({ + "sub-01": { + "func": { + "sub-01_task-nback_run-1_bold.nii.gz": "", + "sub-01_task-nback_run-2_bold.nii.gz": "", + }, + }, + "sub-02": { + "func": { + "sub-02_task-nback_run-1_bold.nii.gz": "", + "sub-02_task-nback_run-2_bold.nii.gz": "", + }, + }, + "task-nback_stim.json": "", + "task-nback_stim.tsv.gz": "", +}) }} + +The following table specifies metadata fields for the +`<matches>_stim.json` file. + +<!-- This block generates a metadata table. +These tables are defined in + src/schema/rules/sidecars +The definitions of the fields specified in these tables may be found in + src/schema/objects/metadata.yaml +A guide for using macros can be found at + https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md +--> +{{ MACROS___make_sidecar_table(["continuous.Continuous"]) }} + +Additional metadata may be included as in +[any TSV file](../common-principles.md#tabular-files) to specify, for +example, the units of the recorded time series for each column.