Differences

This shows you the differences between two versions of the page.

--- visual3d:documentation:emg:processing_tools [2024/06/14 17:11] – created sgranger
+++ visual3d:documentation:emg:processing_tools [2024/07/17 15:45] (current) – created sgranger
@@ Line 1: / Line 1: @@
-|===== Contents =====\\ \\ \\ \\ * [[#General_Processing_Steps|1 General Processing Steps]]\\ * [[#Helpful_Pipeline_Functions|2 Helpful Pipeline Functions]]\\ * [[#Meta_Commands|3 Meta Commands]]\\ * [[#Removing_Noise_from_EMG_Signals|4 Removing Noise from EMG Signals]]\\ * [[#Normalization_and_Scaling_Methods|5 Normalization and Scaling Methods]]|
+====== Processing Tools ======
-===== General Processing Steps =====
+==== Introduction ====
-Processing EMG signals typically follows some variation of the following steps:
+The purpose is to offset trial data to accommodate for any DC shift. Quantifying the EMG background noise based on a "Resting Trial" using the following algorithm:
-. High Pass Filter
+Find overall mean of trial:
-. Low Pass Filter
-. Rectify Data
-. Filter Noise
-. Normalize and Scale Data
-It should be noted that within both this page and external literature, the term "Linear Envelope" refers to an EMG signal that has been rectified and low pass filtered.
-Visual3D has a number of helpful pipeline functions (linked below) that can automate the general processing steps.
+if positive, subtract mean from all values to offset overall average to zero
+if negative, add mean to all values to offset overall average to zero.
+Rectify trial around the zero baselines
-===== Helpful Pipeline Functions =====
+Calculate threshold values for each channel of EMG (level of digitized baseline noise).
-The following links will redirect you to pages detailing the use of Visual3D pipeline commands that are commonly used in the general processing of EMG data:
+Determine noise threshold (i.e., the value determined from the resting EMG values fall below; calculated by passing a ceiling through data at successively higher levels until all data values for the 5 second duration fall below the ceiling.
+==== EMG_Resting_Background ====
-  * [[Visual3D:Documentation:EMG:Filtering:Removing_DC_Bias|High Pass Filter (Removing DC Bias)]]
+You can remove the background using a Meta-Command (as described below), or you can see [[Visual3D:Documentation:EMG:Filtering:Resting_Background_Noise_Offset|here]] for an example implementing this in a script.
-  * [[Lowpass_Filter|Lowpass Filter]]
-  * [[Rectify|Rectify]]
-  * [[Moving_RMS|Moving RMS]]
-  * [[Teager_Kaiser_Energy|Teager Kaiser Energy Operator]]
-  * [[Assign_Tags_To_File|Assign Tags To File]]
-===== Meta Commands =====
+==== EMG_Resting_Background Meta-Command ====
-This page deals with several examples of using Visual3D [[Pipeline_Commands:Meta_Commands|Meta-Commands]]. Meta commands are essentially a way for you to write and upload your own function to the Visual3D pipeline. They have the file extension **".v3m"**. Meta commands must be stored in a folder labelled **Meta-Commands**, which should be located in the Visual3D **Plugins** folder. The Plugins folder may not exist, so you may have to create it yourself. If you receive errors after running a meta-command, navigate to **Edit > Preferences** in Visual3D and check that the directory of the Plugins folder matches the location Visual3D is looking for it in. Restart Visual3D before running the command again.
+The following Meta Command can be Cut-and-Paste into a file named **EMG_Resting_Background.v3m**
-===== Removing Noise from EMG Signals =====
+<code>
+! BEGIN_META
+! META_CMD_NAME=EMG_Resting_Background
+! META_PARAM= SIGNAL_NAMES:string::yes
+! META_PARAM= SIGNAL_FOLDER:string::yes
+! META_PARAM= RESULT_FOLDER:string::yes
+! END_META
-**Download the [[https://www.has-motion.com/download/examples/EMG/EMG_NoiseReduction_Example.zip|EMG_NoiseReductionExample]] here.**
+Set_Pipeline_Parameter
+/PARAMETER_NAME=FOLDER
+/PARAMETER_VALUE=::SIGNAL_FOLDER
+! /PARAMETER_VALUE_SEARCH_FOR=
+! /PARAMETER_VALUE_REPLACE_WITH=
+! /PARAMETER_VALUE_PREFIX=
+! /PARAMETER_VALUE_APPEND=
+;
-The text below describes two common methods of removing noise from EMG signals. Before using these methods, ensure you have performed a high and low pass filter on the raw data. You do not need to rectify your data to use the Root Mean Square method or the Teagan Kaiser Energy Operator method as they will both rectify your signals for you.
+Set_Pipeline_Parameter
+/PARAMETER_NAME=RESULT
+/PARAMETER_VALUE=::RESULT_FOLDER
+! /PARAMETER_VALUE_SEARCH_FOR=
+! /PARAMETER_VALUE_REPLACE_WITH=
+! /PARAMETER_VALUE_PREFIX=
+! /PARAMETER_VALUE_APPEND=
+;
-**1. Root Mean Square (RMS):** The RMS method is typically used when finding overall energy, muscle activation patterns, or for fatigue analysis. The RMS method takes the square root of the mean square of a set of values. Because it deals with the mean square of a data set, the input EMG signal does not need to be rectified before calculating the RMS. Example application of this command shown below:
+! ---------------------------------------------------------------
-<code>
+! Offset trial data to accommodate for any DC shift
-! Example 1: Use the Moving RMS Command to Process EMG Data
+! (find overall mean of trial&ldots;if positive,
-! Apply a high pass filter with 50 Hz cutoff
+! subtract mean from all values to offset overall average to zero&ldots;
-Highpass_Filter
+! if negative, add mean to all values to offset overall average to zero).
-/Signal_Types=ANALOG
+! Rectify trial around the zero baselines
-/Signal_Names=EMG1+EMG2+EMG3
+! (all values set to absolute values).
-/Signal_Folder=ORIGINAL
+! ---------------------------------------------------------------
-! /Result_Suffix=
-! /Result_Folder=PROCESSED
+For_Each
-! /Filter_Class=BUTTERWORTH
+/ITERATION_PARAMETER_NAME=INDEX
-/Frequency_Cutoff= 50
+/ITEMS=::SIGNAL_NAMES
-/Num_Reflected= 0
-/Total_Buffer_Size=100
-/Num_Bidirectional_Passes=1
 ;
-! Apply a low pass filter with 500 Hz cutoff
-Lowpass_Filter
+Metric_Mean
-/Signal_Types=ANALOG
+/RESULT_METRIC_NAME=_MEAN
-/Signal_Names=EMG1+EMG2+EMG3
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
-/Signal_Folder=PROCESSED
+! /RESULT_METRIC_FOLDER=PROCESSED
-! /Result_Suffix=
+/SIGNAL_TYPES=ANALOG
-! /Result_Folder=PROCESSED
+/SIGNAL_NAMES=::INDEX
-! /Filter_Class=BUTTERWORTH
+/SIGNAL_FOLDER=::FOLDER
-/Frequency_Cutoff= 500
+! /SIGNAL_COMPONENTS=X
-/Num_Reflected= 0
+/EVENT_SEQUENCE=
-/Total_Buffer_Size=100
+/EXCLUDE_EVENTS=
-/Num_Bidirectional_Passes=1
+/GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+Evaluate_Expression
+/EXPRESSION=ABS(ANALOG&:&:&::FOLDER&:&:&::INDEX&-&METRIC::PROCESSED&:&:&::INDEX&_MEAN)
+/RESULT_NAME=::INDEX
+/RESULT_TYPE=ANALOG
+/RESULT_FOLDER=::RESULT
+;
+End_For_Each
+/ITERATION_PARAMETER_NAME=INDEX
+;
+! ---------------------------------------------------------------
+! Calculated threshold values for each channel of EMG
+! (level of digitized baseline noise).
+! Apply noise threshold (i.e., the value determined from the
+! resting EMG values fall below).  Calculated by passing a
+! ceiling through data at successively higher levels until
+! all data values for the 5 second duration fall below the ceiling.
+! ---------------------------------------------------------------
+Metric_Maximum
+/RESULT_METRIC_NAME=_REST
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
+/RESULT_METRIC_FOLDER=::RESULT
+/SIGNAL_TYPES=ANALOG
+/SIGNAL_NAMES=
+/SIGNAL_FOLDER=::RESULT
+/SIGNAL_COMPONENTS=X
+/EVENT_SEQUENCE=
+/EXCLUDE_EVENTS=
+/GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+/CREATE_GLOBAL_MAXIMUM=TRUE
 ;
-! Moving RMS with 100 millisecond window
-Moving_RMS
-/SIGNAL_TYPES=ANALOG
-/SIGNAL_NAMES=EMG1+EMG2+EMG3
-/SIGNAL_FOLDER=PROCESSED
-! /RESULT_SUFFIX=
-/RESULT_FOLDER=RMS
-/NUM_WINDOW_FRAMES= ( 0.1*PARAMETER::ANALOG::RATE ) + 1
-;
 </code>
-**2. Teager Kaiser Energy Operator (TKEO):** The TKEO method is typically used when finding muscle onset/offset contracts and analyzing frequency data. The TKEO method is a signal processing technique used to extract information from a time-series signal. It involves calculating the Teager energy of the signal, which is a measure of the signal's instantaneous power, and then smoothing the energy values using a Kaiser window. The resulting smoothed energy values can be used to identify important features in the signal, such as peaks or changes in frequency. Example application of this command shown below:
+==== Madonna EMG Remove Background Meta-Command ====
+The following Meta Command removes the background noise from the EMG signals and can be Cut-and-Paste into a file named **Madonna_EMG_Remove_Background.v3m**
 <code>
-! Example 2: Use the TKEO Command to Process EMG Data
+! BEGIN_META
-Highpass_Filter
+! META_CMD_NAME=Madonna EMG Remove Background
+! META_PARAM= SIGNAL_NAMES:string::yes
+! META_PARAM= SIGNAL_FOLDER:string::yes
+! META_PARAM= RESULT_FOLDER:string::yes
+! META_PARAM= BACKGROUND_FOLDER:string::yes
+! END_META
+Set_Pipeline_Parameter
+/PARAMETER_NAME=FOLDER
+/PARAMETER_VALUE=::SIGNAL_FOLDER
+;
+Set_Pipeline_Parameter
+/PARAMETER_NAME=RESULT
+/PARAMETER_VALUE=::RESULT_FOLDER
+;
+! ---------------------------------------------------------------
+! Remove the EMG background noise
+! ---------------------------------------------------------------
+For_Each
+/ITERATION_PARAMETER_NAME=INDEX
+/ITEMS=::SIGNAL_NAMES
+;
+Evaluate_Expression
+/EXPRESSION=ABS(ANALOG&:&:&::FOLDER&:&:&::INDEX&& - GLOBAL::METRIC&:&:&::BACKGROUND_FOLDER&:&:&::INDEX&_REST_MAX)
+/RESULT_NAME=::INDEX
+/RESULT_TYPE=ANALOG
+/RESULT_FOLDER=::RESULT
+;
+Set_Data_To_New_Values
 /SIGNAL_TYPES=ANALOG
-/SIGNAL_FOLDER=ORIGINAL
+/SIGNAL_NAMES=::INDEX
-/SIGNAL_NAMES=EMG_C
+/SIGNAL_FOLDER=::RESULT
-/RESULT_FOLDER=PROCESSED
+! /SIGNAL_COMPONENTS=ALL_COMPONENTS
 ! /RESULT_SUFFIX=
-! /FILTER_CLASS=BUTTERWORTH
+/RESULT_FOLDER=::RESULT
-/FREQUENCY_CUTOFF=20
+! /EVENT_SEQUENCE=
-/NUM_REFLECTED=0
+! /EXCLUDE_EVENTS=
-! /NUM_EXTRAPOLATED=0
+/START_FRAME=1
-/TOTAL_BUFFER_SIZE=100
+/END_FRAME=EOF
-! /NUM_BIDIRECTIONAL_PASSES=1
+! /USE_POINT_RATE=TRUE
+/REPLACEMENT_VALUES=0
+/THRESHOLD_HIGH=DATA_NOT_FOUND
+/THRESHOLD_LOW=GLOBAL::METRIC&:&:&::BACKGROUND_FOLDER&:&:&::INDEX&_REST_MAX
+;
+End_For_Each
+/ITERATION_PARAMETER_NAME=INDEX
 ;
-Lowpass_Filter
+</code>
-/SIGNAL_TYPES=ANALOG
-/SIGNAL_FOLDER=ORIGINAL
+==== An example Visual3D Pipeline Command to call these Meta-Commands ====
-/SIGNAL_NAMES=EMG_C
-/RESULT_FOLDER=PROCESSED
+In this example, some files are TAGGED as REST, EMG, and GAIT.
-! /RESULT_SUFFIX=
-! /FILTER_CLASS=BUTTERWORTH
+<code>
-/FREQUENCY_CUTOFF=6.0
+!Make the Resting Trial the Active File.
-/NUM_REFLECTED=6
-! /NUM_EXTRAPOLATED=0
+For_Each
-/TOTAL_BUFFER_SIZE=6
+/ITERATION_PARAMETER_NAME=TAGS
-! /NUM_BIDIRECTIONAL_PASSES=1
+/ITEMS=REST
 ;
-Teager_Kaiser_Energy
-/SIGNAL_TYPES=ANALOG
+Select_Active_File
-/SIGNAL_FOLDER=ORIGINAL
+/FILE_NAME=::TAGS
-/SIGNAL_NAMES=EMG_C
+!/QUERY=
-! /RESULT_TYPES=
-/RESULT_FOLDERS=PROCESSED
-/RESULT_NAME=EMG_C_TKEO
-! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=
 ;
-</code>
-**3. Integrating EMG Signals:** Integrating EMG signals can be useful for quantifying muscle activity, comparing muscle activity between conditions, and assessing fatigue. The result of integrating an EMG signal (an iEMG) is a single metric value of microvolts or millivolts. While this isn't strictly a noise reduction method, it does have applications once a signal has been filtered. An example of using Visual3D's pipeline commands to integrate an EMG signal can be found here: [[Visual3D:Documentation:EMG:Filtering:Integrate_EMG|EMG Integrate]].
+! Calculates resting background by calling the EMG_Resting_Background Meta-Command.
-**4. Removing Background Noise Example:** The [[Visual3D:Documentation:EMG:Filtering:Removing_Background_Noise|Removing Background Noise]] page shows an example of using the Visual3D pipeline and Meta Commands to implement a noise reduction algorithm. The algorithm finds the mean of the data, rectifies the data around a mean baseline, and calculates threshold values to store as a global variable.
+EMG_Resting_Background
-===== Normalization and Scaling Methods =====
+/SIGNAL_NAMES=LGAS+LGLU+LMED+LTIB+LVAS+RGAS+RGLU+RMED+RTIB+RVAS
+/SIGNAL_FOLDER=EMG_FILTERED
+/RESULT_FOLDER=EMG_BACKGROUND
+;
-Normalizing data is a useful transformation for comparing signals across groups of data. This section discusses several methods of using Visual3D's pipeline features to normalize and scale EMG signals after they have been filtered.
+End_For_Each
+/ITERATION_PARAMETER_NAME=TAGS
+;
-**1. Normalize and Scale EMG Signal to Global Maximum:** One method of normalizing EMG signals is to use the maximum voluntary contraction (MVC) value. MVC values are an EMG signal measuring during a maximal effort task , which is then used as a reference value to normalize EMG signals during all subsequent experimental tasks. What this translates to in Visual3D is first calculating the maximum value of the reference signal and store it in the Global workspace, then normalize your signals by dividing them by this global metric. Sample files and pipelines are available [[Visual3D:Documentation:EMG:Processing:Normalize_EMG_to_MVC|here]] and [[Visual3D:Documentation:EMG:Processing:Normalize_EMG_to_Generic_Global_Variable|here]].
+! This loop will remove the resting background from the signals.
-**2. Compute Normalization Scale Factors:** Here are two examples of the steps that would be used to compute a normalization factor using MVC data.
+For_Each
-**Example 1: Single MVC Trial:** The process for computing a normalization factor from a single MVC value uses the following general steps:
+/ITERATION_PARAMETER_NAME=TAGS
-  - Process EMG
+/ITEMS=EMG+GAIT
-    - High pass filter (remove DC offset)
+;
-    - Calculate RMS of predetermined time intervals (example: 0.02 seconds)
-  - Normalize
-    - Calculate the average of the processed signal over 30 second intervals
-    - Get the maximum of the 30 second interval
-    - Normalize by dividing the average by the maximum
-**Example 2: Multiple MVC Trials**
+Select_Active_File
-  - Process EMG
+/FILE_NAME=::TAGS
-    - High pass filter (remove DC offset)
+!/QUERY=
-    - Calculate RMS of predetermined time intervals (example: 0.02 seconds)
+;
-  - Normalize
-    - Calculate the average of the processed signal over some time interval (in this example: 0.5 seconds)
-    - Get the maximum of the processed signal
-    - Calculate the maximum of the average signal
-    - Normalize by dividing the processed signal by the maximum average over the interval
-Sample files and pipelines are available [[Visual3D:Documentation:EMG:Processing:Normalize_EMG_to_Maximum_30_second_interval|here]].
+! Call the EMG_Remove_Background Meta-Command
-|**3. Normalize to Maximum within Gait Cycle:** The image to the (right) shows four "checkpoints" in normalizing a signal to the maximum within a gait cycle.\\ \\ * First graph: raw EMG signal with gait events RHS (pink) and RTO (purple). These correspond to the signal within ANALOG::ORIGINAL in the Sample_Workspace.cmz download.\\ * Second graph: the linear envelope (ANALOG::ENVELOPE) showing the rectified and smoothed signal with maximums A (~0.76) and B (~0.69).\\ * Third graph: all frames within each gait cycle set to the maximum value, and all other frames are set to zero.\\ * Fourth graph: the linear envelope signal is divided by the maximum of the corresponding gait cycle. Notice how the peaks of both cycles are now 1, and all values outside the defined event sequence are set to "data not found".\\ \\ Sample files and pipelines are available [[Visual3D:Documentation:EMG:Processing:Normalize_EMG_Signal_to_Maximum_Within_Gait_Cycle|here]].  |  [[File:EMG_Normalized_Gait_Cycle.png|{{/images/thumb/2/22/EMG_Normalized_Gait_Cycle.png/500px-EMG_Normalized_Gait_Cycle.png?500x354}}]]|
+EMG_Remove_Background
+/SIGNAL_NAMES=LGAS+LGLU+LMED+LTIB+LVAS+RGAS+RGLU+RMED+RTIB+RVAS
+/SIGNAL_FOLDER=EMG_FILTERED
+/BACKGROUND_FOLDER=EMG_BACKGROUND
+/RESULT_FOLDER=EMG_PROCESSED
+;
+End_For_Each
+/ITERATION_PARAMETER_NAME=TAGS
+;
+</code>
-Retrieved from ""