[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

@@ -372,6 +372,14 @@ 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
+  description: |
+    Placement of the electrode(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
@@ -403,6 +411,13 @@ reference__ieeg:
     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 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_frame:
   name: reference_frame
   display_name: Reference frame

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,15 @@ _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:
+    - $ref: objects.enums.Other.value
 _GeneticLevelEnum:
   type: string
   enum:

src/schema/objects/metadata.yaml

@@ -916,6 +916,70 @@ EMGChannelCount:
     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 Procedure
+  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
+    (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.
+  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.
+  type: string
 EOGChannelCount:
   name: EOGChannelCount
   display_name: EOG Channel Count

src/schema/objects/modalities.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/rules/checks/deprecations.yml

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

src/schema/rules/json/emg.yaml

@@ -0,0 +1,69 @@
+#
+# Groups of related metadata fields
+#
+# Assumptions: never need disjunction of selectors
+# 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:
+    - datatype == "emg"
+    - suffix == "coordsystem"
+  fields:
+    EMGCoordinateSystem: required
+    EMGCoordinateUnits: required
+    EMGCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `EMGCoordinateSystem` is `"Other"`
+
+EMGCoordsystemOther:
+  selectors:
+    - datatype == "emg"
+    - suffix == "coordsystem"
+    - '"EMGCoordinateSystem" in json'
+    - json.EMGCoordinateSystem == "Other"
+  fields:
+    EMGCoordinateSystemDescription: required
+
+# Fields relating to the position of anatomical landmark measured during an EMG session/run
+EMGCoordsystemLandmark:
+  selectors:
+    - datatype == "emg"
+    - suffix == "coordsystem"
+  fields:
+    AnatomicalLandmarkCoordinates: recommended
+    AnatomicalLandmarkCoordinateSystem:
+      level: recommended
+      description_addendum: Preferably the same as the `EMGCoordinateSystem`.
+    AnatomicalLandmarkCoordinateUnits: recommended
+
+EMGCoordsystemLandmarkDescriptionRec:
+  selectors:
+    - datatype == "emg"
+    - suffix == "coordsystem"
+    - json.AnatomicalLandmarkCoordinateSystem != "Other"
+  fields:
+    AnatomicalLandmarkCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `AnatomicalLandmarkCoordinateSystem` is `"Other"`
+
+EMGCoordsystemLandmarkDescriptionReq:
+  selectors:
+    - datatype == "emg"
+    - suffix == "coordsystem"
+    - json.AnatomicalLandmarkCoordinateSystem == "Other"
+  fields:
+    AnatomicalLandmarkCoordinateSystemDescription: required

src/schema/rules/sidecars/emg.yaml

@@ -0,0 +1,96 @@
+#
+# Groups of related metadata fields
+#
+# Assumptions: never need disjunction of selectors
+# Assumptions: top-to-bottom overrides is sufficient logic
+
+---
+EMGHardware:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    Manufacturer: recommended
+    ManufacturersModelName: recommended
+    SoftwareVersions: recommended
+    DeviceSerialNumber: recommended
+# TODO?
+#   AmplifierType: recommended
+#   ElectrodeManufacturer: recommended
+#   ElectrodeManufacturersModelName: recommended
+
+EMGTaskInformation:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    TaskName:
+      level: required
+      description_addendum: |
+        A recommended convention is to name resting state task using labels
+        beginning with `rest`.
+    TaskDescription: recommended
+    Instructions:
+      level: recommended
+      description_addendum: |
+        This is especially important in context of resting state recordings, to distinguish
+        resting positions with different postures (for example, `"seated"`, `"reclined"`).
+
+EMGInstitutionInformation:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    InstitutionName: recommended
+    InstitutionAddress: recommended
+    InstitutionalDepartmentName: recommended
+
+# Specific EMG fields MUST be present
+EMGRequired:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    EMGPlacementScheme: required
+    EMGReference: required
+    SamplingFrequency:
+      level: required
+      description_addendum: |
+        The sampling frequency of data channels that deviate from the main sampling
+        frequency SHOULD be specified in the `channels.tsv` file.
+    PowerLineFrequency: required
+    SoftwareFilters: required
+
+# Specific EMG fields SHOULD be present
+EMGRecommended:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    ElectrodeMaterial: recommended
+    ElectrodeType: recommended
+    EMGChannelCount: recommended
+    EMGGround: recommended
+    EpochLength: recommended
+    HardwareFilters: 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
+EMGOptional:
+  selectors:
+    - datatype == "emg"
+    - suffix == "emg"
+  fields:
+    ECGChannelCount: optional
+    EOGChannelCount: optional
+    MISCChannelCount: optional
+    ElectricalStimulation: optional
+    ElectricalStimulationParameters: optional

src/schema/rules/tabular_data/emg.yaml

@@ -0,0 +1,45 @@
+---
+EMGChannels:
+  selectors:
+    - datatype == "emg"
+    - suffix == "channels"
+    - extension == ".tsv"
+  initial_columns:
+    - name__channels
+    - type__channels
+    - units
+  columns:
+    name__channels: required
+    type__channels: required
+    units: required
+    description: optional
+    sampling_frequency: optional
+    reference__emg: optional
+    low_cutoff: optional
+    high_cutoff: optional
+    notch: optional
+    status: optional
+    status_description: optional
+  index_columns: [name__channels]
+  additional_columns: allowed_if_defined
+
+EMGElectrodes:
+  selectors:
+    - datatype == "emg"
+    - suffix == "electrodes"
+    - extension == ".tsv"
+  initial_columns:
+    - name__electrodes
+    - x
+    - y
+    - z
+  columns:
+    name__electrodes: required
+    x: required
+    y: required
+    z: optional
+    type__electrodes: recommended
+    material: recommended
+    impedance: recommended
+  index_columns: [name__electrodes]
+  additional_columns: allowed_if_defined