Merge pull request #1888 from effigies/fix/coordsystem-task

[FIX] Allow (but discourage) task, acquisition and run entities for coordsystem.json and electrodes.tsv

src/modality-specific-files/electroencephalography.md

@@ -439,6 +439,12 @@ landmarks or fiducials during an EEG session/run, must be stored separately in
 the corresponding `*_T1w.json` or `*_T2w.json` file and should be expressed in
 voxels (starting from `[0, 0, 0]`).
 
+`*_coordsystem.json` files SHOULD NOT be duplicated for each data file,
+for example, across multiple tasks.
+The [inheritance principle](../common-principles.md#the-inheritance-principle) MUST
+be used to find the appropriate coordinate system description for a given data file.
+If electrodes are repositioned, it is RECOMMENDED to use multiple sessions to indicate this.
+
 ### Example `*_coordsystem.json`
 
 ```JSON

src/modality-specific-files/intracranial-electroencephalography.md

@@ -403,6 +403,12 @@ A guide for using macros can be found at
 -->
 {{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemPositions") }}
 
+`*_coordsystem.json` files SHOULD NOT be duplicated for each data file,
+for example, across multiple tasks.
+The [inheritance principle](../common-principles.md#the-inheritance-principle) MUST
+be used to find the appropriate coordinate system description for a given data file.
+If electrodes are repositioned, it is RECOMMENDED to use multiple sessions to indicate this.
+
 ### Recommended 3D coordinate systems
 
 It is preferred that electrodes are localized in a 3D coordinate system (with

src/modality-specific-files/magnetoencephalography.md

@@ -429,6 +429,11 @@ For more information on typical coordinate systems for MEG-MRI coregistration:
 or:
 [Coordinate Systems - Brainstorm toolbox](https://neuroimage.usc.edu/brainstorm/CoordinateSystems)
 
+`*_coordsystem.json` files SHOULD NOT be duplicated for each data file,
+for example, across multiple tasks.
+The [inheritance principle](../common-principles.md#the-inheritance-principle) MUST
+be used to find the appropriate coordinate system description for a given data file.
+
 ## Landmark photos (`*_photo.<extension>`)
 
 Photos of the anatomical landmarks and/or head localization coils

src/modality-specific-files/near-infrared-spectroscopy.md

@@ -427,6 +427,12 @@ A guide for using macros can be found at
 
 {{ MACROS___make_json_table(["json.nirs.AnatomicalLandmark", "json.nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }}
 
+`*_coordsystem.json` files SHOULD NOT be duplicated for each data file,
+for example, across multiple tasks.
+The [inheritance principle](../common-principles.md#the-inheritance-principle) MUST
+be used to find the appropriate coordinate system description for a given data file.
+If optodes are repositioned, it is RECOMMENDED to use multiple sessions to indicate this.
+
 ### Example `*_coordsystem.json`
 
 ```json

src/schema/rules/checks/channels.yaml

@@ -0,0 +1,34 @@
+---
+ElectrodeSpecificity:
+  issue:
+    code: EXCESSIVE_ELECTRODE_SPECIFICITY
+    message: |
+      Task, acquisition or run entities detected in electrodes.tsv.
+      Electrode definitions should generally not vary within a session.
+      Consider removing the excess entity/entities or create a new
+      session each time electrodes are reconfigured.
+    level: warning
+  selectors:
+    - suffix == 'electrodes'
+    - extension == '.tsv'
+  checks:
+    - '!("task" in entities)'
+    - '!("acquisition" in entities)'
+    - '!("run" in entities)'
+
+CoordsystemSpecificity:
+  issue:
+    code: EXCESSIVE_COORDSYSTEM_SPECIFICITY
+    message: |
+      Task, acquisition or run entities detected in coordsystem.tsv.
+      Coordinate systems should generally not vary within a session.
+      Consider removing the excess entity/entities or create new
+      sessions when multiple coordinate systems are appropriate.
+    level: warning
+  selectors:
+    - suffix == 'coordsystem'
+    - extension == '.json'
+  checks:
+    - '!("task" in entities)'
+    - '!("acquisition" in entities)'
+    - '!("run" in entities)'

src/schema/rules/files/raw/channels.yaml

@@ -45,6 +45,7 @@ coordsystem:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
 
 # (i)EEG has a space entity
@@ -69,6 +70,7 @@ electrodes:
   entities:
     subject: required
     session: optional
+    task: optional
     acquisition: optional
     run: optional
     space: optional