add EMG support

Author: drammock

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/modality-specific-files/electromyography.md

@@ -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
@@ -252,6 +259,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
@@ -372,6 +388,13 @@ participant_id:
     matching a participant entity found in the dataset.
   type: string
   pattern: ^sub-[0-9a-zA-Z+]+$
+placement__emg:
+  name: placement
+  display_name: Placement Scheme
+  description: |
+    Placement of the sensor(s) on the body (for example, "palmar side of lower arm").
+    It can refer to an external vocabulary for describing body parts.
+  type: string
 placement__motion:
   name: placement
   display_name: Placement
@@ -395,6 +418,13 @@ 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: Electrode reference
+  description: |
+    Specification of the reference (for example, `ulnar styloid process`, `ElectrodeName01`, `n/a`).
+  type: string
 # reference column for channels.tsv files for iEEG data
 reference__ieeg:
   name: reference
@@ -509,6 +539,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` electrode is subtracted, to yield
+    the channel's data.
+  type: string
 size:
   name: size
   display_name: Electrode size
@@ -603,6 +640,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/modality-specific-files/images/emg_electrodes1.png

@@ -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/columns.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/common_principles.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:

src/schema/objects/datatypes.yaml

@@ -9,6 +9,21 @@ ACCELChannelCount:
     Number of acceleration channels.
   type: integer
   minimum: 0
+AnchorCoordinates:
+  name: AnchorCoordinates
+  display_name: Anchor Coordinates
+  description: |
+    Coordinates of the `AnchorElectrode` in the parent (anatomical) coordinate system.
+    This should be an array of numbers of length 3, in the units given in
+    `EMGCoordinateSystemUnits` within the JSON object named in `ParentCoordinateSystem`.
+  type: array
+AnchorElectrode:
+  name: AnchorElectrode
+  display_name: Anchor Electrode
+  description: |
+    Name of the electrode in the child (device) coordinate system whose coordinates in
+    the parent (anatomical) coordinate system are given in `AnchorCoordinates`.
+  type: string
 Acknowledgements:
   name: Acknowledgements
   display_name: Acknowledgements
@@ -911,13 +926,100 @@ EEGReference:
     this field should have a general description and the channel specific
     reference should be defined in the `channels.tsv` file.
   type: string
+ElectrodeMaterial:
+  name: ElectrodeMaterial
+  display_name: Electrode Material
+  description: |
+    Material of the electrode (for example, `Tin`, `Ag/AgCl`, `Gold`).
+  type: string
+ElectrodeType:
+  name: ElectrodeType
+  display_name: Electrode type
+  description: |
+    Type of the electrode (for example, cup, ring, clip-on, wire, needle).
+  type: string
 EMGChannelCount:
   name: EMGChannelCount
   display_name: EMG Channel Count
   description: |
     Number of EMG channels.
   type: integer
   minimum: 0
+EMGCoordinateSystem:
+  name: EMGCoordinateSystem
+  display_name: EMG Coordinate System
+  description: |
+    Defines the coordinate system for the EMG sensors.
+
+    See the
+    [Coordinate Systems Appendix](SPEC_ROOT/appendices/coordinate-systems.md)
+    for a list of restricted keywords for coordinate systems.
+    If `"Other"`, provide definition of the coordinate system in
+    `EMGCoordinateSystemDescription`.
+  anyOf:
+    - $ref: objects.enums._EMGCoordSys
+EMGCoordinateSystemDescription:
+  name: EMGCoordinateSystemDescription
+  display_name: EMG Coordinate System Description
+  description: |
+    Free-form text description of the coordinate system, typically defining the origin
+    and positive x,y,z axis directions, relative to skeletal landmarks.
+    May also include a link to a documentation page or paper describing the
+    system in greater detail.
+  type: string
+EMGCoordinateUnits:
+  name: EMGCoordinateUnits
+  display_name: EMG Coordinate Units
+  description: |
+    Units of the coordinates of `EMGCoordinateSystem`.
+  type: string
+  enum:
+    - m
+    - mm
+    - cm
+    - n/a
+EMGGround:
+  name: EMGGround
+  display_name: EMG Ground
+  description: |
+    Description of the location of the ground electrode
+    (for example, `"right radial styloid process"`).
+  type: string
+EMGPlacementScheme:
+  name: EMGPlacementScheme
+  display_name: EMG Placement Scheme
+  description: |
+    The name of a standardized electrode placement procedure (for example, `"SENIAM 8"`)
+    or a description of the procedure used.
+    Descriptions SHOULD NOT simply give the name of the targeted muscle (use the
+    `target_muscle` column in `channels.tsv` for that), but rather SHOULD reflect the
+    process used by the researcher(s) when placing electrodes.
+    For example, EMG electrode sites may be chosen by *visual reference* to target muscles,
+    by *palpation* of the skin to locate target muscles, by *functional localization*
+    (temporary electrode placement at several sites during prescribed behavior,
+    until a site yielding strong EMG signal is found), or by *measured distances*
+    (either absolute or proportional) relative to skeletal landmarks.
+    In datasets involving multiple EMG recording units placed at different sites in which
+    different placement procedures were used for different sites, the procedures for each
+    site SHOULD be described in the `placement_scheme` column of `channels.tsv` instead,
+    and the value of `EMGPlacementScheme` SHOULD be a non-empty string such as
+    "channel-specific" or "see channels.tsv" or similar.
+  type: string
+EMGReference:
+  name: EMGReference
+  display_name: EMG Reference
+  description: |
+    Description of the reference electrode location when the same reference was used for
+    all channels (often called a "monopolar" recording).
+    If different channels have different reference electrodes, this field should contain
+    a non-empty string such as "channel-specific" and each channel-specific reference
+    should be described in the `reference` column of `channels.tsv`.
+    For bipolar recording devices (where a single sensor unit contains two rigidly
+    separated contacts, and the paired contacts are not listed independently in
+    `electrodes.tsv`), the value of `reference` (in `channels.tsv`, for single channels)
+    or `EMGReference` (in `emg.json`, when all channels were bipolar) should be "bipolar".
+
+  type: string
 EOGChannelCount:
   name: EOGChannelCount
   display_name: EOG Channel Count
@@ -1709,6 +1811,13 @@ IntendedFor__ds_relative:
             format: bids_uri
           - type: string
             format: dataset_relative
+InterelectrodeDistance:
+  name: InterelectrodeDistance
+  display_name: Interelectrode Distance
+  description: |
+    Distance between pairs or grids of electrodes rigidly attached to the same sensor device.
+  type: number
+  unit: mm
 InversionTime:
   name: InversionTime
   display_name: Inversion Time
@@ -2503,6 +2612,13 @@ ParallelReductionFactorOutOfPlane:
     Corresponds to [DICOM Tag 0018, 9155](https://dicomlookup.com/dicomtags/(0018,9155))
     `Parallel Reduction Factor out-of-plane`.
   type: number
+ParentCoordinateSystem:
+  name: ParentCoordinateSystem
+  display_name: Parent Coordinate System
+  description: |
+    The name of a JSON mapping key that defines the parent (anatomical) coordinate system
+    in which this child (device) coordinate system is anchored.
+  type: string
 PartialFourier:
   name: PartialFourier
   display_name: Partial Fourier
@@ -3300,6 +3416,13 @@ SinglesRate:
   type: array
   items:
     type: number
+SkinPreparation:
+  name: SkinPreparation
+  display_name: Skin Preparation
+  description: |
+    How skin was prepared prior to sensor device placement, for example, `"alcohol wipe"`
+    or `"abrasive gel"`.
+  type: string
 SkullStripped:
   name: SkullStripped
   display_name: Skull Stripped

src/schema/objects/enums.yaml

@@ -8,6 +8,10 @@ eeg:
   display_name: Electroencephalography
   description: |
     Data acquired with EEG.
+emg:
+  display_name: Electromyography
+  description: |
+    Data acquired with EMG.
 ieeg:
   display_name: Intracranial Electroencephalography
   description: |

src/schema/objects/metadata.yaml

@@ -611,7 +611,12 @@ electrodes:
   value: electrodes
   display_name: Electrodes
   description: |
-    File that gives the location of (i)EEG electrodes.
+    File that gives the location of (i)EEG or EMG electrodes.
+emg:
+  value: emg
+  display_name: Electromyography
+  description: |
+    Electromyography recording data.
 epi:
   value: epi
   display_name: EPI

src/schema/objects/modalities.yaml

@@ -1,3 +1,4 @@
+---
 AnatomicalLandmarkCoordinateSystemDeprecation:
   issue:
     code: ELEKTA_NEUROMAG_DEPRECATED

src/schema/objects/suffixes.yaml

@@ -7,6 +7,7 @@ channels:
     - .tsv
   datatypes:
     - eeg
+    - emg
     - ieeg
     - nirs
   entities:
@@ -40,6 +41,7 @@ coordsystem:
   extensions:
     - .json
   datatypes:
+    - emg
     - meg
     - nirs
   entities:
@@ -65,23 +67,31 @@ electrodes:
     - .json
     - .tsv
   datatypes:
-    - eeg
-    - ieeg
+    - emg
   entities:
     subject: required
     session: optional
     task: optional
     acquisition: optional
     run: optional
+
+ # (i)EEG can also have `space` entity
+electrodes__eeg:
+  $ref: rules.files.raw.channels.electrodes
+  datatypes:
+    - eeg
+    - ieeg
+  entities:
+    $ref: rules.files.raw.channels.electrodes.entities
     space: optional
 
 # MEG has an additional entity available
 electrodes__meg:
-  $ref: rules.files.raw.channels.electrodes
+  $ref: rules.files.raw.channels.electrodes__eeg
   datatypes:
     - meg
   entities:
-    $ref: rules.files.raw.channels.electrodes.entities
+    $ref: rules.files.raw.channels.electrodes__eeg.entities
     processing: optional
 
 optodes: