[ENH] extension for electromyography (EMG) - BEP042

mkdocs.yml

@@ -20,6 +20,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

@@ -188,6 +188,10 @@ For example:
 
 -   (publication forthcoming)
 
+#### EMG
+
+-   (publication forthcoming)
+
 ### Research Resource Identifier (RRID)
 
 BIDS has also a

src/schema/objects/columns.yaml

@@ -89,6 +89,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:
   anyOf:
     - type: string
     - type: number
+group__emg:
+  name: group
+  display_name: Channel group
+  description: |
+    Which group of channels this channel belongs to (typically this indicates channels
+    on the same grid, strip, or other device).
+  anyOf:
+    - type: string
+    - type: number
 handedness:
   name: handedness
   display_name: Subject handedness
@@ -227,7 +243,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
@@ -252,6 +268,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_electrode`
+    when each is independently placed.
+  type: number
+  unit: mm
 low_cutoff:
   name: low_cutoff
   display_name: Low cutoff
@@ -372,6 +397,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
@@ -395,6 +437,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_electrode:
+  name: reference_electrode
+  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
@@ -509,6 +561,14 @@ 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_electrode`'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
@@ -603,6 +663,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: |
@@ -44,6 +45,8 @@ data_type:
 
         14. `mrs` (magnetic resonance spectroscopy)
 
+        15. `emg` (electromyography)
+
 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:
@@ -740,11 +744,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
@@ -759,6 +766,7 @@ MISC:
   display_name: MISC
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -779,6 +787,7 @@ POS:
   value: POS
   display_name: POS
   tags:
+    - emg
     - motion
   description: |
     Position in space, one channel for each spatial axis.
@@ -816,6 +825,7 @@ EOG:
   display_name: EOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -826,6 +836,7 @@ ECG:
   display_name: ECG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -836,6 +847,7 @@ EMG:
   display_name: EMG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -863,6 +875,7 @@ HEOG:
   display_name: HEOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -890,6 +903,7 @@ REF:
   display_name: REF
   tags:
     - eeg
+    - emg
     - ieeg
   description: |
     Reference channel.
@@ -905,11 +919,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
@@ -922,6 +939,7 @@ TRIG:
   display_name: TRIG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs
@@ -932,6 +950,7 @@ VEOG:
   display_name: VEOG
   tags:
     - eeg
+    - emg
     - meg
     - ieeg
     - fnirs