[ENH] Make explicit that "task" metadata applies to "beh" modality (#804

) * Add metadata to JSON files in beh folder * add task metadata to PET * style fix * Revert PET task change * Apply suggestions from code review Co-authored-by: Chris Markiewicz <effigies@gmail.com> * Apply suggestions from code review * STY: Table fences * replace hard coded table with macro call * lint fix * update taskname definition * update instruction definition * remove extra info about task from iEEG as non specific to iEEG * Revert "remove extra info about task from iEEG as non specific to iEEG" This reverts commit 1352662. Co-authored-by: Chris Markiewicz <effigies@gmail.com>
bids-standard · Aug 2, 2021 · 7e01e17 · 7e01e17
1 parent ce79c50
commit 7e01e17
Show file tree

Hide file tree

Showing 7 changed files with 31 additions and 12 deletions.
diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -467,7 +467,7 @@ JSON file.
    {
       "RepetitionTime": "REQUIRED",
       "VolumeTiming": "REQUIRED",
-      "TaskName": "REQUIRED",
+      "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`.")
    }
 ) }}
 
@@ -513,7 +513,7 @@ sparse sequences.
 
 {{ MACROS___make_metadata_table(
    {
-      "Instructions": "RECOMMENDED",
+      "Instructions": ("RECOMMENDED", "This is especially important in context of resting state recordings and distinguishing between eyes open and eyes closed paradigms."),
       "TaskDescription": "RECOMMENDED",
       "CogAtlasID": "RECOMMENDED",
       "CogPOID": "RECOMMENDED",

diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md
@@ -82,7 +82,7 @@ Generic fields MUST be present:
 
 {{ MACROS___make_metadata_table(
    {
-      "TaskName": "REQUIRED",
+      "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
    }
 ) }}
 
@@ -109,7 +109,7 @@ Whenever possible, please avoid using ad-hoc wording.
       ),
       "SoftwareVersions": "RECOMMENDED",
       "TaskDescription": "RECOMMENDED",
-      "Instructions": "RECOMMENDED",
+      "Instructions": ("RECOMMENDED", "This is especially important in context of resting state recordings and distinguishing between eyes open and eyes closed paradigms."),
       "CogAtlasID": "RECOMMENDED",
       "CogPOID": "RECOMMENDED",
       "DeviceSerialNumber": "RECOMMENDED",

diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
@@ -88,7 +88,7 @@ Generic fields MUST be present:
 
 {{ MACROS___make_metadata_table(
    {
-      "TaskName": "REQUIRED",
+      "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
    }
 ) }}
 
@@ -104,7 +104,7 @@ Whenever possible, please avoid using ad hoc wording.
       "ManufacturersModelName": "RECOMMENDED",
       "SoftwareVersions": "RECOMMENDED",
       "TaskDescription": "RECOMMENDED",
-      "Instructions": "RECOMMENDED",
+      "Instructions": ("RECOMMENDED", "This is especially important in context of resting state recordings and distinguishing between eyes open and eyes closed paradigms."),
       "CogAtlasID": "RECOMMENDED",
       "CogPOID": "RECOMMENDED",
       "DeviceSerialNumber": "RECOMMENDED",

diff --git a/src/04-modality-specific-files/04-intracranial-electroencephalography.md b/src/04-modality-specific-files/04-intracranial-electroencephalography.md
@@ -94,7 +94,7 @@ Generic fields MUST be present:
 
 {{ MACROS___make_metadata_table(
    {
-      "TaskName": "REQUIRED",
+      "TaskName": ("REQUIRED", "A RECOMMENDED convention is to name resting state task using labels beginning with `rest`."),
    }
 ) }}
 
@@ -112,7 +112,7 @@ Whenever possible, please avoid using ad hoc wording.
       "ManufacturersModelName": "RECOMMENDED",
       "SoftwareVersions": "RECOMMENDED",
       "TaskDescription": "RECOMMENDED",
-      "Instructions": "RECOMMENDED",
+      "Instructions": ("RECOMMENDED", "This is especially important in context of resting state recordings and distinguishing between eyes open and eyes closed paradigms."),
       "CogAtlasID": "RECOMMENDED",
       "CogPOID": "RECOMMENDED",
       "DeviceSerialNumber": "RECOMMENDED",

diff --git a/src/04-modality-specific-files/07-behavioral-experiments.md b/src/04-modality-specific-files/07-behavioral-experiments.md
@@ -14,8 +14,31 @@ 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`.
 
+Each task has a unique label that MUST only consist of letters and/or numbers
+(other characters, including spaces and underscores, are not allowed) with the
+[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
+Those labels MUST be consistent across subjects and sessions.
+
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label to
 distinguish different conditions present during multiple runs of the same task.
 For example, if a study includes runs of an n-back task, with deep brain
 stimulation turned on or off, the data files may be labelled
 `sub-01_task-nback_acq-dbson_beh.tsv` and `sub-01_task-nback_acq-dbsoff_beh.tsv`.
+
+## RECOMMENDED metadata
+
+In addition of the metadata REQUIRED for some data that can be found in the `beh` folder
+(for example `SamplingFrequency` and `StartTime` for `*_<physio|stim>.tsv.gz` files),
+it is RECOMMENDED to add the following metadata to the JSON files of this folder.
+
+{{ MACROS___make_metadata_table(
+   {
+      "TaskName": "RECOMMENDED",
+      "Instructions": "RECOMMENDED",
+      "TaskDescription": "RECOMMENDED",
+      "CogAtlasID": "RECOMMENDED",
+      "CogPOID": "RECOMMENDED",
+      "InstitutionName": "RECOMMENDED",
+      "InstitutionAddress": "RECOMMENDED",
+   }
+) }}
diff --git a/src/schema/metadata/Instructions.yaml b/src/schema/metadata/Instructions.yaml
@@ -2,6 +2,4 @@
 name: Instructions
 description: |
   Text of the instructions given to participants before the recording.
-  This is especially important in context of resting state recordings and
-  distinguishing between eyes open and eyes closed paradigms.
 type: string
diff --git a/src/schema/metadata/TaskName.yaml b/src/schema/metadata/TaskName.yaml
@@ -7,6 +7,4 @@ description: |
   by removing all non-alphanumeric (`[a-zA-Z0-9]`) characters.
   For example `TaskName` `"faces n-back"` will correspond to task label
   `facesnback`.
-  A RECOMMENDED convention is to name resting state task using labels beginning
-  with `rest`.
 type: string