[ENH] BEP042 - extension for electromyography (EMG)

mkdocs.yml

@@ -24,6 +24,7 @@ nav:
           - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
           - Motion: modality-specific-files/motion.md
           - Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.md
+          - Electromyography: modality-specific-files/electromyography.md
       - Derivatives:
           - BIDS Derivatives: derivatives/introduction.md
           - Common data types and metadata: derivatives/common-data-types.md

src/introduction.md

@@ -192,6 +192,10 @@ For example:
     Scientific Data 12, (13841).
     [doi:10.1038/s41597-025-05543-2](https://doi.org/10.1038/s41597-025-05543-2)
 
+#### EMG
+
+-   (publication forthcoming)
+
 ### Research Resource Identifier (RRID)
 
 BIDS has also a

src/schema/meta/associations.yaml

@@ -75,7 +75,7 @@ bvec:
 
 channels:
   selectors:
-    - intersects([suffix], ['eeg', 'ieeg', 'meg', 'nirs', 'motion', 'optodes'])
+    - intersects([suffix], ['eeg', 'emg', 'ieeg', 'meg', 'nirs', 'motion', 'optodes'])
     - extension != '.json'
   target:
     suffix: channels
@@ -93,11 +93,23 @@ coordsystem:
 
 electrodes:
   selectors:
-    - intersects([suffix], ['eeg', 'ieeg', 'meg'])
+    - intersects([suffix], ['eeg', 'emg', 'ieeg', 'meg'])
     - extension != '.json'
   target:
     suffix: electrodes
     extension: .tsv
     entities:
       - space
   inherit: true
+
+coordsystems:
+  selectors:
+    - datatype == 'emg'
+    - intersects([suffix], ['emg', 'electrodes'])
+    - extension != '.json'
+  target:
+    suffix: coordsystem
+    extension: .json
+    entities:
+      - space
+  inherit: true

src/schema/meta/context.yaml

@@ -269,14 +269,35 @@ properties:
             description: 'Path to associated electrodes.tsv file'
             type: string
       coordsystem:
-        description: 'Coordinate system file'
+        description: 'Coordinate system file (first found)'
         type: object
         required: [path]
         additionalProperties: false
         properties:
           path:
             description: 'Path to associated coordsystem file'
             type: string
+      coordsystems:
+        description: 'Coordinate system files (all)'
+        type: object
+        required: [paths, spaces, ParentCoordinateSystems]
+        additionalProperties: false
+        properties:
+          paths:
+            description: 'Paths to associated coordsystem files'
+            type: array
+            items:
+              type: string
+          spaces:
+            description: 'Space entity labels extracted from file names'
+            type: array
+            items:
+              type: string
+          ParentCoordinateSystems:
+            description: 'ParentCoordinateSystem fields loaded from files'
+            type: array
+            items:
+              type: string
   # The following properties are populated if the current file is of an appropriate type
   columns:
     description: 'TSV columns, indexed by column header, values are arrays with column contents'

src/schema/objects/columns.yaml

@@ -92,6 +92,13 @@ component:
     - $ref: objects.enums.quat_y.value
     - $ref: objects.enums.quat_z.value
     - $ref: objects.enums.quat_w.value
+coordinate_system:
+  name: coordinate_system
+  display_name: Coordinate System
+  description: |
+    Name of the coordinate system defined in `coordsystem.json` in which the electrode's
+    `x`, `y`, and (optionally) `z` coordinates are given.
+  type: string
 detector__channels:
   name: detector
   display_name: Detector Name
@@ -179,6 +186,15 @@ group__channel:
     This is relevant because one group has one cable-bundle and noise can be shared.
     This can be a name or number.
   type: string
+group__emg:
+  name: group
+  display_name: Electrode or channel group
+  description: |
+    Which group the electrode or channel belongs to (typically this indicates electrodes
+    or bipolar channels on the same grid, strip, or other device).
+  anyOf:
+    - type: string
+    - type: number
 handedness:
   name: handedness
   display_name: Subject handedness
@@ -228,7 +244,7 @@ high_cutoff:
   description: |
     Frequencies used for the low-pass filter applied to the channel in Hz.
     If no low-pass filter applied, use `n/a`.
-    Note that hardware anti-aliasing in A/D conversion of all MEG/EEG electronics
+    Note that hardware anti-aliasing in A/D conversion of all MEG/EEG/EMG electronics
     applies a low-pass filter; specify its frequency here if applicable.
   type: number
   unit: Hz
@@ -253,6 +269,15 @@ index:
   description: |
     The label integer index.
   type: integer
+interelectrode_distance:
+  name: interelectrode_distance
+  display_name: Interelectrode Distance
+  description: |
+    Distance between adjacent electrodes (in a pair or grid) that are rigidly attached to
+    the same sensor device, or between the `signal_electrode` and its `reference`
+    when each is independently placed.
+  type: number
+  unit: mm
 low_cutoff:
   name: low_cutoff
   display_name: Low cutoff
@@ -374,6 +399,23 @@ participant_id:
     matching a participant entity found in the dataset.
   type: string
   pattern: ^sub-[0-9a-zA-Z+]+$
+placement_description:
+  name: placement_description
+  display_name: Placement Scheme Description
+  description: |
+    Additional details of the approach to EMG sensor placement.
+    See description of the `EMGPlacementSchemeDescription` field in `*_emg.json`.
+  type: string
+placement_scheme:
+  name: placement_scheme
+  display_name: Placement Scheme
+  description: |
+    A description of the electrode placement procedure used.
+    See description of the `EMGPlacementScheme` field in `*_emg.json`.
+  type: string
+  enum:
+    - measured
+    - other
 placement__motion:
   name: placement
   display_name: Placement
@@ -397,6 +439,16 @@ reference__eeg:
     This column is not needed when it is common to all channels.
     In that case the reference electrode(s) can be specified in `*_eeg.json` as `EEGReference`).
   type: string
+# reference column for channels.tsv files for EMG data
+reference__emg:
+  name: reference
+  display_name: Reference electrode
+  description: |
+    The reference for the given channel.
+    When the reference is an electrode in `*_electrodes.tsv`, use the name of that electrode.
+    For channels originating from bipolar devices, use `"bipolar"`.
+    For non-EMG channels (for example, trigger channels, microphones) use `"n/a"`.
+  type: string
 # reference column for channels.tsv files for iEEG data
 reference__ieeg:
   name: reference
@@ -513,6 +565,13 @@ short_channel:
     The total number of channels listed as short channels
     SHOULD be stored in `ShortChannelCount` in `*_nirs.json`.
   type: boolean
+signal_electrode:
+  name: signal_electrode
+  display_name: Signal electrode
+  description: |
+    The name of the electrode from which the `reference`'s signal is subtracted to yield the channel's data.
+    For channels originating from bipolar devices, the `signal_electrode` MAY be the same as the channel `name`.
+  type: string
 size:
   name: size
   display_name: Electrode size
@@ -608,6 +667,14 @@ strain_rrid:
     of the strain of the species, for example: `RRID:IMSR_JAX:000664`.
   type: string
   format: rrid
+target_muscle:
+  name: target_muscle
+  display_name: Target muscle
+  description: |
+    Name of the muscle(s) from which the EMG signal in this channel is believed to originate.
+    When exact muscle is unknown (such as when using electrode grids that cover multiple muscles),
+    groups of muscles may be named instead (for example "flexors of the left forearm").
+  type: string
 time:
   name: time
   display_name: Time

src/schema/objects/common_principles.yaml

@@ -6,8 +6,9 @@
 data_acquisition:
   display_name: Data acquisition
   description: |
-    A continuous uninterrupted block of time during which a brain scanning instrument was acquiring data according to
-    particular scanning sequence/protocol.
+    A continuous uninterrupted block of time during which a brain scanning instrument
+    or an electromyography recording device was acquiring data
+    according to a particular scanning sequence/protocol.
 data_type:
   display_name: Data type
   description: |
@@ -45,11 +46,14 @@ data_type:
 
         15. `phenotype` (measurement and survey data)
 
+        16. `emg` (electromyography)
+
     For files that are subject- and session- specific, the data type directory
     is nested inside those directories.
     `phenotype` data files are aggregated across subjects and sessions,
     and so the `phenotype/` directory is placed in the dataset root.
 
+
 dataset:
   display_name: Dataset
   description: |

src/schema/objects/datatypes.yaml

@@ -20,6 +20,10 @@ eeg:
   value: eeg
   display_name: Electroencephalography
   description: Electroencephalography
+emg:
+  value: emg
+  display_name: Electromyography
+  description: Measurements of muscular activity.
 fmap:
   value: fmap
   display_name: Field maps

src/schema/objects/enums.yaml

@@ -7,6 +7,10 @@ _EEGCoordSys:
     - $ref: objects.enums.EEGLAB.value
     - $ref: objects.enums.EEGLAB-HJ.value
     - $ref: objects.enums.Other.value
+_EMGCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.Other.value
 _GeneticLevelEnum:
   type: string
   enum:
@@ -756,11 +760,14 @@ LATENCY:
   value: LATENCY
   display_name: LATENCY
   tags:
+    - emg
     - motion
   description: |
     Latency of samples in seconds from recording onset.
     MUST be in form of `ss[.000000]`,
     where `[.000000]` is an optional subsecond resolution between 1 and 6 decimal points.
+    Note that `LATENCY` channels typically contain timestamps from an _external_ clock
+    source, often with the intent of synchronizing data across multiple devices.
 MAGN:
   value: MAGN
   display_name: MAGN
@@ -775,6 +782,7 @@ MISC:
   display_name: MISC
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -795,6 +803,7 @@ POS:
   value: POS
   display_name: POS
   tags:
+    - emg
     - motion
   description: |
     Position in space, one channel for each spatial axis.
@@ -832,6 +841,7 @@ EOG:
   display_name: EOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -842,6 +852,7 @@ ECG:
   display_name: ECG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -852,6 +863,7 @@ EMG:
   display_name: EMG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -879,6 +891,7 @@ HEOG:
   display_name: HEOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -906,6 +919,7 @@ REF:
   display_name: REF
   tags:
     - eeg
+    - emg
     - ieeg
   description: |
     Reference channel.
@@ -921,11 +935,14 @@ SYSCLOCK:
   display_name: SYSCLOCK
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
   description: |
-    System time showing elapsed time since trial started.
+    Elapsed time since trial/recording start, as provided by the recording device.
+    For device-external timestamp signals, use `LATENCY`.
+    For TTL-based synchronization signals, use `TRIG`.
 TEMP:
   value: TEMP
   display_name: TEMP
@@ -938,6 +955,7 @@ TRIG:
   display_name: TRIG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -948,6 +966,7 @@ VEOG:
   display_name: VEOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs