WIP

Author: drammock

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,12 +388,11 @@ participant_id:
     matching a participant entity found in the dataset.
   type: string
   pattern: ^sub-[0-9a-zA-Z]+$
-# TODO revisit whether example is sufficient
 placement__emg:
   name: placement
-  display_name: Placement
+  display_name: Placement Scheme
   description: |
-    Placement of the electrode(s) on the body (for example, "palmar side of lower arm").
+    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:
@@ -403,20 +418,20 @@ 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 iEEG data
-reference__ieeg:
+# reference column for channels.tsv files for EMG data
+reference__emg:
   name: reference
   display_name: Electrode reference
   description: |
-    Specification of the reference (for example, `mastoid`, `ElectrodeName01`, `intracranial`, `CAR`, `other`, `n/a`).
-    If the channel is not an electrode channel (for example, a microphone channel) use `n/a`.
+    Specification of the reference (for example, `ulnar styloid process`, `ElectrodeName01`, `n/a`).
   type: string
-# reference column for channels.tsv files for EMG data
-reference__emg:
+# reference column for channels.tsv files for iEEG data
+reference__ieeg:
   name: reference
   display_name: Electrode reference
   description: |
-    Specification of the reference (for example, `ulnar styloid process`, `ElectrodeName01`, `n/a`).
+    Specification of the reference (for example, `mastoid`, `ElectrodeName01`, `intracranial`, `CAR`, `other`, `n/a`).
+    If the channel is not an electrode channel (for example, a microphone channel) use `n/a`.
   type: string
 reference_frame:
   name: reference_frame

src/schema/objects/columns.yaml

@@ -7,11 +7,6 @@ _EEGCoordSys:
     - $ref: objects.enums.EEGLAB.value
     - $ref: objects.enums.EEGLAB-HJ.value
     - $ref: objects.enums.Other.value
-# TODO: I think "Other" is all we want at this point, since SENIAM isn't a coordsystem
-#       and anything else will need to specify origin and axis directions relative to
-#       skeletal landmarks in `EMGCoordinateSystemDescription`. But we should probably
-#       still define this (single-element) enum now, so it's easier to add predefined
-#       coordinate systems later (since we know folks are working on publishing them).
 _EMGCoordSys:
   type: string
   enum:

src/schema/objects/enums.yaml

@@ -909,6 +909,18 @@ 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
@@ -958,27 +970,38 @@ EMGGround:
   type: string
 EMGPlacementScheme:
   name: EMGPlacementScheme
-  display_name: EMG Placement Procedure
+  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 reflect the process used by the researcher(s) when placing electrodes,
-    and SHOULD NOT simply give the name of the targeted muscle (use `TargetMuscle` for that).
-    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
+    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
+    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 scheme used and (when applicable) of location of the
-    reference electrode in the raw recordings (for example, `"left ulnar styloid process"`).
-    For bipolar channels, specify `EMGReference` as "bipolar".
-    If different channels have different references, this field should contain a general
-    description and the channel specific reference should be defined in the `channels.tsv` file.
+    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
@@ -1770,6 +1793,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
@@ -3357,6 +3387,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/metadata.yaml

@@ -612,6 +612,11 @@ electrodes:
   display_name: Electrodes
   description: |
     File that gives the location of (i)EEG electrodes.
+emg:
+  value: emg
+  display_name: Electromyography
+  description: |
+    Electromyography recording data.
 epi:
   value: epi
   display_name: EPI

src/schema/objects/suffixes.yaml

@@ -73,24 +73,22 @@ EMGRecommended:
     EMGGround: recommended
     EpochLength: recommended
     HardwareFilters: recommended
+    InterelectrodeDistance: recommended
     RecordingDuration: recommended
     RecordingType: recommended
     SubjectArtefactDescription: recommended
-    TargetMuscle: recommended
     TriggerChannelCount: recommended
 
 # Specific EMG fields MAY be present
-# TODO: InterElectrodeDistance: in channels.tsv probably, only for bipolar channels
-#       ElectrodeGroup: not sure this is still needed given our use of `acq`
-#       ElectrodeOrientation: incorporate into EMGPlacementScheme?
-#       SkinPreparation: abrasive gel, alcohol wipe
+# TODO: do we want/need any of these?
+#       ECGChannelCount: optional
+#       EOGChannelCount: optional
+#       MISCChannelCount: optional
+#       ElectricalStimulation: optional
+#       ElectricalStimulationParameters: optional
 EMGOptional:
   selectors:
     - datatype == "emg"
     - suffix == "emg"
   fields:
-    ECGChannelCount: optional
-    EOGChannelCount: optional
-    MISCChannelCount: optional
-    ElectricalStimulation: optional
-    ElectricalStimulationParameters: optional
+    SkinPreparation: optional

src/schema/rules/sidecars/emg.yaml

@@ -14,13 +14,18 @@ EMGChannels:
     units: required
     description: optional
     sampling_frequency: optional
+    signal_electrode: optional
     reference__emg: optional
+    group__channel: optional
+    target_muscle: optional
+    placement: optional
+    interelectrode_distance: recommended
     low_cutoff: optional
     high_cutoff: optional
     notch: optional
     status: optional
     status_description: optional
-  index_columns: [name__channels]
+  index_columns: [name__channels, group__channels]
   additional_columns: allowed_if_defined
 
 EMGElectrodes:
@@ -33,13 +38,17 @@ EMGElectrodes:
     - x
     - y
     - z
+    - coordinate_system
   columns:
     name__electrodes: required
     x: required
     y: required
     z: optional
+    coordinate_system: recommended
     type__electrodes: recommended
     material: recommended
     impedance: recommended
-  index_columns: [name__electrodes]
+    group__channel: optional
+    placement: optional
+  index_columns: [name__electrodes, group__channel]
   additional_columns: allowed_if_defined