Merge branch 'master' of https://github.com/markmikkelsen/bids-specif…

…ication

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"

src/modality-specific-files/physiological-and-other-continuous-recordings.md → 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.

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.

src/schema/objects/metadata.yaml

@@ -232,6 +232,20 @@ B0FieldSource:
     - type: array
       items:
         type: string
+B0ShimmingTechnique:
+  name: B0ShimmingTechnique
+  display_name: B0 Shimming Technique
+  description: |
+    The technique used to shim the *B<sub>0</sub>* field (for example, `"Dynamic shim updating"`
+    or `"FASTMAP"`).
+  type: string
+B1ShimmingTechnique:
+  name: B1ShimmingTechnique
+  display_name: B1 Shimming Technique
+  description: |
+    The technique used to shim the *B<sub>1</sub>* field (for example, `"Simple phase align"`
+    or `"Pre-saturated TurboFLASH"`).
+  type: string
 BIDSVersion:
   name: BIDSVersion
   display_name: BIDS Version
@@ -2214,6 +2228,12 @@ NumberOfVolumesDiscardedByUser:
     `"NumberOfVolumesDiscardedByUser"` field.
   type: integer
   minimum: 0
+NumberReceiveCoilActiveElements:
+  name: NumberReceiveCoilActiveElements
+  display_name: Number of Receive Coil Active Elements
+  description: |
+    The number of active RF elements used by the receive coil.
+  type: integer
 NumberShots:
   name: NumberShots
   display_name: Number Shots
@@ -2233,6 +2253,12 @@ NumberShots:
     - type: array
       items:
         type: number
+NumberTransmitCoilActiveElements:
+  name: NumberTransmitCoilActiveElements
+  display_name: Number of Transmit Coil Active Elements
+  description: |
+    The number of active RF elements used by the transmit coil.
+  type: integer
 NumericalAperture:
   name: NumericalAperture
   display_name: Numerical Aperture
@@ -3594,6 +3620,18 @@ VolumeTiming:
   items:
     type: number
     unit: s
+WaterSuppression:
+  name: WaterSuppression
+  display_name: Water Suppression
+  description: |
+    Boolean indicating whether water suppression was used prior to acquisition.
+  type: boolean
+WaterSuppressionTechnique:
+  name: WaterSuppressionTechnique
+  display_name: Water Suppression Technique
+  description: |
+    The name of the pulse sequence used for water suppression (for example, `"CHESS"`, `"VAPOR"`).
+  type: string
 WholeBloodAvail:
   name: WholeBloodAvail
   display_name: Whole Blood Avail

src/schema/rules/sidecars/mri.yaml

@@ -30,10 +30,12 @@ MRIHardware:
       level: recommended, but required for Arterial Spin Labeling
     ReceiveCoilName: recommended
     ReceiveCoilActiveElements: recommended
+    NumberReceiveCoilActiveElements: optional
     GradientSetType: recommended
     MRTransmitCoilSequence: recommended
     MatrixCoilMode: recommended
     CoilCombinationMethod: recommended
+    NumberTransmitCoilActiveElements: optional
 
 MRISample:
   selectors:
@@ -77,6 +79,10 @@ MRISequenceSpecifics:
     SpoilingRFPhaseIncrement: optional
     SpoilingGradientMoment: optional
     SpoilingGradientDuration: optional
+    WaterSuppression: optional
+    WaterSuppressionTechnique: optional
+    B0ShimmingTechnique: optional
+    B1ShimmingTechnique: optional
 
 PETMRISequenceSpecifics:
   selectors: