From 09fcdedd64fcdaa0861b391e55310d9e22cb22fc Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Thu, 5 Dec 2024 17:05:55 -0600 Subject: [PATCH] first draft of modality-specific doc --- mkdocs.yml | 1 + src/introduction.md | 4 + .../electromyography.md | 475 ++++++++++++++++++ 3 files changed, 480 insertions(+) create mode 100644 src/modality-specific-files/electromyography.md diff --git a/mkdocs.yml b/mkdocs.yml index 08fd23ef68..e5fa039a4f 100644 --- a/mkdocs.yml +++ b/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 diff --git a/src/introduction.md b/src/introduction.md index a07b654b2c..a6281e893e 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -188,6 +188,10 @@ For example: - (publication forthcoming) +#### EMG + +- (publication forthcoming) + ### Research Resource Identifier (RRID) BIDS has also a diff --git a/src/modality-specific-files/electromyography.md b/src/modality-specific-files/electromyography.md new file mode 100644 index 0000000000..bee8c2aa4a --- /dev/null +++ b/src/modality-specific-files/electromyography.md @@ -0,0 +1,475 @@ +# Electromyography + +Support for Electromyography (EMG) was developed as a +[BIDS Extension Proposal](../extensions.md#bids-extension-proposals). +Please see [Citing BIDS](../introduction.md#citing-bids) on how to appropriately credit +this extension when referring to it in the context of the academic literature. + +!!! example "Example datasets" + + Electromyography datasets formatted according to this specification are available on + the [BIDS examples repository](https://github.com/bids-standard/bids-examples#emg) + and can be emulated when curating new datasets. + +## EMG data + +{{ MACROS___make_filename_template( +"raw", +datatypes=["emg"], +suffixes=["motion", "channels", "events"]) +}} + +The EMG community uses a variety of formats for storing raw data, and there is +no single standard that all researchers agree on. For BIDS, EMG data MUST be +stored in one of the following formats: + +| **Format** | **Extension(s)** | **Description** | +| ------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [European data format](https://www.edfplus.info/) | `.edf` | Each recording consists of a single `.edf` file. [`edf+`](https://www.edfplus.info/specs/edfplus.html) files are permitted. The capital `.EDF` extension MUST NOT be used. | +| TODO OTHER ALLOWED (VENDOR-SPECIFIC?) FORMAT(S)? | `.TODO` | TODO. | + +It is RECOMMENDED to use the European data format. +It is furthermore discouraged to use the other accepted formats over this RECOMMENDED format, +particularly because there are conversion scripts available in most commonly used +programming languages to convert data into the RECOMMENDED format. + +Future versions of BIDS may extend this list of supported file formats. +File formats for future consideration MUST have open access documentation, MUST have +open source implementation for both reading and writing in at least two programming +languages and SHOULD be widely supported in multiple software packages. +Other formats that may be considered in the future should have a clear added advantage +over the existing formats and should have wide adoption in the BIDS community. + +We encourage users to provide additional metadata extracted from the +manufacturer-specific data files in the sidecar JSON file. + +Note the RecordingType, which depends on whether the data stream on disk is interrupted or not. +Continuous data is by definition 1 segment without interruption. + +Epoched data consists of multiple segments that all have the same length +(for example, corresponding to trials) and that have gaps in between. +Discontinuous data consists of multiple segments of different length, +for example due to a pause in the acquisition. + +### Terminology: Electrodes vs. Channels + +For proper documentation of EMG recording metadata it is important to understand the +difference between electrode and channel: an EMG electrode is a sensor placed on the +skin, whereas a channel is the combination of the analog differential amplifier and +analog-to-digital converter that result in a potential (voltage) difference that is +stored in the EMG dataset. +We employ the following short definitions: + +- Electrode = A single point of contact between the acquisition system and the + recording site (for example, scalp, neural tissue, ...). + Multiple electrodes can be organized as arrays, grids, leads, strips, probes, + shafts, caps (for EEG), and so forth. + +- Channel = A single analog-to-digital converter in the recording system that + regularly samples the value of a transducer, which results in the signal being + represented as a time series in the digitized data. + This can be connected to two electrodes (to measure the potential difference between + them), a magnetic field or magnetic gradient sensor, temperature sensor, + accelerometer, and so forth. + +Although the _reference_ and _ground_ electrodes are often referred to as channels, +they are in most common EMG systems not recorded by themselves. +Therefore they are not represented as channels in the data. +The type of referencing for all channels and optionally the location of the reference +electrode and the location of the ground electrode MAY be specified. + +### Sidecar JSON (`*_emg.json`) + +For consistency between studies and institutions, +we encourage users to extract the values of metadata fields from the actual raw data. +Whenever possible, please avoid using ad hoc wording. + +Those fields MUST be present: + + +{{ MACROS___make_sidecar_table("emg.EMGRequired") }} + +Those fields SHOULD be present: + + +{{ MACROS___make_sidecar_table("emg.EMGRecommended") }} + +These fields MAY be present: + + +{{ MACROS___make_sidecar_table("emg.EMGOptional") }} + +Note that the date and time information SHOULD be stored in the study key file +([`scans.tsv`](../modality-agnostic-files.md#scans-file)). +Date time information MUST be expressed as indicated in [Units](../common-principles.md#units) + +#### Hardware information + + +{{ MACROS___make_sidecar_table("emg.EMGHardware") }} + +#### Task information + + +{{ MACROS___make_sidecar_table("emg.EMGTaskInformation") }} + +Note that the `TaskName` field does not have to be a "behavioral task" that subjects perform, +but can reflect some information about the conditions present when the data was acquired +(for example, `"treatment"`, `"control"`, or `"sleep"`). + +#### Institution information + + +{{ MACROS___make_sidecar_table("emg.EMGInstitutionInformation") }} + +#### Example `*_emg.json` + + + + +```JSON +{ + "EMGChannelCount":4, + "EMGGround":"TODO", + "EMGPlacementScheme":"TODO", + "EMGReference":"TODO", + "HardwareFilters":{"Highpass RC filter": {"Half amplitude cutoff (Hz)": 0.0159, "Roll-off": "6dBOctave"}}, + "InstitutionAddress":"300 Pasteur Dr, Stanford, CA 94305", + "InstitutionName":"Stanford Hospital and Clinics", + "Instructions":"Jump straight upward as high as you can, while keeping your arms at your sides.", + "Manufacturer":"Delsys", + "ManufacturersModelName":"Trigno® Galileo", + "MiscChannelCount":0, + "PowerLineFrequency":60, + "RecordingDuration":123.456, + "RecordingType":"continuous", + "SamplingFrequency":1000, + "SoftwareFilters":"n/a", + "TaskDescription":"jumping with stiff arms", + "TaskName":"jumping", +} +``` + +## Channels description (`*_channels.tsv`) + + +{{ MACROS___make_filename_template("raw", datatypes=["emg"], suffixes=["channels"]) }} + +A channel represents one time series recorded with the recording system +(for example, there can be a bipolar channel, recorded from two electrodes or contact points on the tissue). +Although this information can often be extracted from the EMG recording, +listing it in a simple `.tsv` document makes it easy to browse or search +(for example, searching for recordings with a sampling frequency of >=1000 Hz). +Hence, the `channels.tsv` file is RECOMMENDED. +Channels SHOULD appear in the table in the same order they do in the EMG data file. +Any number of additional columns MAY be provided to provide additional information about the channels. +Note that electrode positions SHOULD NOT be added to this file but to `*_electrodes.tsv`. + +The columns of the channels description table stored in `*_channels.tsv` are: + + +{{ MACROS___make_columns_table("emg.EMGChannels") }} + +Restricted keyword list for field type in alphabetic order (shared with the MEG +and EEG modality; however, only types that are common in EMG data are listed here). +Note that upper-case is REQUIRED: + + +| **Keyword** | **Description** | +| ----------- | ---------------------------------------------------------------------- | +| EEG | Electrode channel from electroencephalogram | +| ECOG | Electrode channel from electrocorticogram (intracranial) | +| SEEG | Electrode channel from stereo-electroencephalogram (intracranial) | +| DBS | Electrode channel from deep brain stimulation electrode (intracranial) | +| VEOG | Vertical EOG (electrooculogram) | +| HEOG | Horizontal EOG | +| EOG | Generic EOG channel if HEOG or VEOG information not available | +| ECG | ElectroCardioGram (heart) | +| EMG | ElectroMyoGram (muscle) | +| TRIG | Analog (TTL in Volt) or digital (binary TTL) trigger channel | +| AUDIO | Audio signal | +| PD | Photodiode | +| EYEGAZE | Eye Tracker gaze | +| PUPIL | Eye Tracker pupil diameter | +| MISC | Miscellaneous | +| SYSCLOCK | System time showing elapsed time since trial started | +| ADC | Analog to Digital input | +| DAC | Digital to Analog output | +| REF | Reference channel | +| OTHER | Any other type of channel | + +Examples of free-form text for field `description`: + +- n/a +- stimulus +- response +- skin conductance +- battery status + +### Example `*_channels.tsv` + +See also the corresponding [`electrodes.tsv` example](#example-electrodestsv). + +```Text +name type units description reference status status_description +VEOG VEOG uV left eye VEOG-, VEOG+ good n/a +FDI EMG uV left first dorsal interosseous FDI-, FDI+ good n/a +Cz EEG uV n/a REF bad high frequency noise +UADC001 MISC n/a envelope of audio signal n/a good n/a +``` + +## Electrodes description (`*_electrodes.tsv`) + + +{{ MACROS___make_filename_template("raw", datatypes=["emg"], suffixes=["electrodes"]) }} + +File that gives the location of EMG electrodes. +Descriptions of electrode location in `*_electrodes.tsv` files MUST reflect the process +used by the researcher(s) when placing electrodes, electrode locations MUST NOT simply +give the name of the targeted muscle. +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) in a coordinate system defined by skeletal landmarks. +Electrode location descriptions MAY refer to reference texts in regard to electrode placement, +such as SENIAM. +Measured coordinates are expected to conform to the `EMGCoordinateSystem` and +`EMGCoordinateUnits` fields in `*_coordsystem.json`. +**If measured coordinates are provided in an `*_electrodes.tsv` file, a +[`*_coordsystem.json`](#coordinate-system-json-_coordsystemjson) file MUST be specified as well**. +The order of the required columns in the `*_electrodes.tsv` file MUST be as listed below. + + +{{ MACROS___make_columns_table("emg.EMGElectrodes") }} + +The [`acq-