update after (near-)finalization of fields/columns; add example image

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
@@ -524,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
@@ -618,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

@@ -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/columns.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
@@ -909,6 +924,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 +985,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 +1808,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
@@ -2560,6 +2605,13 @@ ParallelReductionFactorOutOfPlane:
     as they imply different methods of accelerating the acquisition.
     Corresponds to DICOM Tag 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
@@ -3357,6 +3409,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

@@ -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/metadata.yaml

@@ -5,18 +5,6 @@
 # Assumptions: top-to-bottom overrides is sufficient logic
 
 ---
-# General fields
-EMGCoordsystemGeneral:
-  selectors:
-    - datatype == "emg"
-    - suffix == "coordsystem"
-  fields:
-    IntendedFor:
-      level: optional
-      description_addendum: |
-        This identifies the origin and axes directions for coordinate systems
-        used to describe digitized EMG electrode locations.
-
 # Fields relating to the EMG electrode positions
 EMGCoordsystemPositions:
   selectors:
@@ -38,17 +26,15 @@ EMGCoordsystemOther:
   fields:
     EMGCoordinateSystemDescription: required
 
-# Fields relating to the position of anatomical landmark measured during an EMG session/run
-EMGCoordsystemLandmark:
+# Fields relating to the linkage between child (device) and parent (anatomical) coordinate systems
+EMGCoordsystemAnchor:
   selectors:
     - datatype == "emg"
     - suffix == "coordsystem"
   fields:
-    AnatomicalLandmarkCoordinates: recommended
-    AnatomicalLandmarkCoordinateSystem:
-      level: recommended
-      description_addendum: Preferably the same as the `EMGCoordinateSystem`.
-    AnatomicalLandmarkCoordinateUnits: recommended
+    ParentCoordinateSystem: optional
+    AnchorCoordinates: optional
+    AnchorElectrode: optional
 
 EMGCoordsystemLandmarkDescriptionRec:
   selectors:

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/json/emg.yaml

@@ -14,13 +14,18 @@ EMGChannels:
     units: required
     description: optional
     sampling_frequency: optional
-    reference__emg: optional
+    signal_electrode: recommended
+    reference__emg: recommended
+    group__channel: recommended
+    target_muscle: recommended
+    placement__emg: recommended
+    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: required
     type__electrodes: recommended
     material: recommended
     impedance: recommended
-  index_columns: [name__electrodes]
+    group__channel: recommended
+    placement__emg: optional
+  index_columns: [name__electrodes, group__channel]
   additional_columns: allowed_if_defined