Differences

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

--- visual3d:documentation:emg:processing:normalize_emg_to_mvc [2024/06/19 12:47] – sgranger
+++ visual3d:documentation:emg:processing:normalize_emg_to_mvc [2024/07/17 15:45] (current) – created sgranger
@@ Line 1: / Line 1: @@
-{{**normalize emg signal to maximum within gait cycle**
+====== Normalize EMG to MVC ======
-for this example, the goal is as follows:
+**Normalize EMG Signal to Maximum Within Gait Cycle**
-  * process the raw emg signal
+For this example, the goal is as follows:
-    * in this example, a simple linear envelope was done and saved in analog::envelope
-  * compute the maximum of the emg signal during each gait cycle
-  * normalize the emg signal to the maximum during each gait cycle
-====== sample files ======
+  * Process the raw EMG signal
+    * In this example, a simple linear envelope was done and saved in ANALOG::ENVELOPE
+  * Compute the maximum of the EMG signal during each gait cycle
+  * Normalize the EMG signal to the maximum during each gait cycle
-[[https://www.has-motion.com/download/examples/emg/maximum_per_cycle.zip|you can download the sample files here.]]
+===== Sample Files =====
-the download contains:
+[[https://www.has-motion.com/download/examples/EMG/Maximum_Per_Cycle.zip|You can download the sample files here.]]
-  * sample_workspace.cmz with -
+The download contains:
-    * 2 dynamic trials
-    * processed emg signals (analog::envelope), you should use your own processing, not the example processing used to create this envelope signal
-  * emg_norm_gait_cycle.v3s (example pipeline script)
-  * emg_norm_gait_cycle.v3m (example meta-command)
-  * call_emg_norm_gait_cycle_meta.v3s (example pipeline script calling meta-command)
-====== script explanation ======
+  * Sample_Workspace.cmz with -
+    * 2 Dynamic Trials
+    * Processed EMG signals (ANALOG::ENVELOPE), you should use your own processing, not the example processing used to create this envelope signal
+  * EMG_Norm_Gait_Cycle.v3s (Example Pipeline Script)
+  * EMG_Norm_Gait_Cycle.v3m (Example Meta-Command)
+  * Call_EMG_Norm_Gait_Cycle_Meta.v3s (Example Pipeline Script calling Meta-Command)
-|the image on the right corresponds to four steps in the pipeline below. as a general outline, the procedure has the following checkpoints:\\ \\ * 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".  |  emg_normalized_gait_cycle.png|
+===== Script Explanation =====
-====== example pipeline script ======
+|The image on the right corresponds to four steps in the pipeline below. As a general outline, the procedure has the following checkpoints:\\ \\ * 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".  |  {{:EMG_Normalized_Gait_Cycle.png}}|
+===== Example Pipeline Script =====
 <code>
-set_pipeline_parameter
+Set_Pipeline_Parameter
-/parameter_name=r_emg_signal_list
+/PARAMETER_NAME=R_EMG_SIGNAL_LIST
-/parameter_value=emg_a+emg_b+emg_c
+/PARAMETER_VALUE=EMG_A+EMG_B+EMG_C
-! /parameter_value_search_for=
+! /PARAMETER_VALUE_SEARCH_FOR=
-! /parameter_value_replace_with=
+! /PARAMETER_VALUE_REPLACE_WITH=
-! /parameter_value_prefix=
+! /PARAMETER_VALUE_PREFIX=
-! /parameter_value_append=
+! /PARAMETER_VALUE_APPEND=
-! /multi_pass=false
+! /MULTI_PASS=FALSE
 ;
-set_pipeline_parameter
+Set_Pipeline_Parameter
-/parameter_name=l_emg_signal_list
+/PARAMETER_NAME=L_EMG_SIGNAL_LIST
-/parameter_value=emg_a+emg_b+emg_c
+/PARAMETER_VALUE=EMG_A+EMG_B+EMG_C
-! /parameter_value_search_for=
+! /PARAMETER_VALUE_SEARCH_FOR=
-! /parameter_value_replace_with=
+! /PARAMETER_VALUE_REPLACE_WITH=
-! /parameter_value_prefix=
+! /PARAMETER_VALUE_PREFIX=
-! /parameter_value_append=
+! /PARAMETER_VALUE_APPEND=
-! /multi_pass=false
+! /MULTI_PASS=FALSE
 ;
-select_active_file
+Select_Active_File
-/file_name=all_files
+/FILE_NAME=ALL_FILES
-! /query=
+! /QUERY=
 ;
-event_define_event_sequence
+Event_Define_Event_Sequence
-/event_sequence_name=rcycle_sequence
+/EVENT_SEQUENCE_NAME=RCYCLE_SEQUENCE
-/event_sequence=rhs+rto
+/EVENT_SEQUENCE=RHS+RTO
-! /exclude_events=
+! /EXCLUDE_EVENTS=
-! /inside_of_sequence=
+! /INSIDE_OF_SEQUENCE=
-! /offset_from_start=
+! /OFFSET_FROM_START=
-! /offset_from_end=
+! /OFFSET_FROM_END=
-! /offset_by=percent
+! /OFFSET_BY=PERCENT
-/event_sequence_instance=0
+/EVENT_SEQUENCE_INSTANCE=0
 ;
-event_define_event_sequence
+Event_Define_Event_Sequence
-/event_sequence_name=lcycle_sequence
+/EVENT_SEQUENCE_NAME=LCYCLE_SEQUENCE
-/event_sequence=lhs+lto
+/EVENT_SEQUENCE=LHS+LTO
-! /exclude_events=
+! /EXCLUDE_EVENTS=
-! /inside_of_sequence=
+! /INSIDE_OF_SEQUENCE=
-! /offset_from_start=
+! /OFFSET_FROM_START=
-! /offset_from_end=
+! /OFFSET_FROM_END=
-! /offset_by=percent
+! /OFFSET_BY=PERCENT
-/event_sequence_instance=0
+/EVENT_SEQUENCE_INSTANCE=0
 ;
-for_each
+For_Each
-/iteration_parameter_name=side
+/ITERATION_PARAMETER_NAME=SIDE
-! /iteration_parameter_count_name=
+! /ITERATION_PARAMETER_COUNT_NAME=
-/items=r+l
+/ITEMS=R+L
 ;
- set_pipeline_parameter
+ Set_Pipeline_Parameter
- /parameter_name=emg_signal_list
+ /PARAMETER_NAME=EMG_SIGNAL_LIST
- /parameter_value=:&:&::side&_emg_signal_list
+ /PARAMETER_VALUE=:&:&::SIDE&_EMG_SIGNAL_LIST
- ! /parameter_value_search_for=
+ ! /PARAMETER_VALUE_SEARCH_FOR=
- ! /parameter_value_replace_with=
+ ! /PARAMETER_VALUE_REPLACE_WITH=
- ! /parameter_value_prefix=
+ ! /PARAMETER_VALUE_PREFIX=
- ! /parameter_value_append=
+ ! /PARAMETER_VALUE_APPEND=
- /multi_pass=true
+ /MULTI_PASS=TRUE
  ;
  ! ---------------------------------------------------------------------
- ! get the maximum number of cycles in a trial the entire cmz file
+ ! Get the maximum number of cycles in a trial the entire CMZ file
  ! ---------------------------------------------------------------------
- ! we're going to loop over every sequence in the trial,
+ ! We're going to loop over every sequence in the trial,
  ! so first calculate the maximum number of sequences in the longest trial
- ! count the number of cycles in each trial
+ ! Count the number of cycles in each trial
- metric_event_sequence_count
+ Metric_Event_Sequence_Count
- /result_metric_folder=emg_norm
+ /RESULT_METRIC_FOLDER=EMG_NORM
- /result_metric_name=&::side&cycle_count
+ /RESULT_METRIC_NAME=&::SIDE&Cycle_Count
- ! /time_interval=
+ ! /TIME_INTERVAL=
- /event_sequence=&::side&cycle_sequence
+ /EVENT_SEQUENCE=&::SIDE&CYCLE_SEQUENCE
- /exclude_events=
+ /EXCLUDE_EVENTS=
- /generate_count_total_in_global=false
+ /GENERATE_COUNT_TOTAL_IN_GLOBAL=FALSE
  ;
- ! calculate the maximum number of cycles across all trials
+ ! Calculate the maximum number of cycles across all trials
- metric_maximum
+ Metric_Maximum
- /result_metric_folder=emg_norm
+ /RESULT_METRIC_FOLDER=EMG_NORM
- /result_metric_name=&::side&cycle_count_global
+ /RESULT_METRIC_NAME=&::SIDE&Cycle_Count_Global
- ! /apply_as_suffix_to_signal_name=false
+ ! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
- /signal_types=metric
+ /SIGNAL_TYPES=METRIC
- /signal_folder=emg_norm
+ /SIGNAL_FOLDER=EMG_NORM
- /signal_names=&::side&cycle_count
+ /SIGNAL_NAMES=&::SIDE&Cycle_Count
- /component_sequence=all
+ /COMPONENT_SEQUENCE=ALL
- /event_sequence=
+ /EVENT_SEQUENCE=
- /exclude_events=
+ /EXCLUDE_EVENTS=
- /sequence_percent_start=
+ /SEQUENCE_PERCENT_START=
- /sequence_percent_end=
+ /SEQUENCE_PERCENT_END=
- /generate_mean_and_stddev=false
+ /GENERATE_MEAN_AND_STDDEV=FALSE
- ! /append_to_existing_values=false
+ ! /APPEND_TO_EXISTING_VALUES=FALSE
- /create_global_maximum=true
+ /CREATE_GLOBAL_MAXIMUM=TRUE
  ;
- ! create a list from 1 to the maximum event sequence in steps of 1
+ ! Create a list from 1 to the maximum event sequence in steps of 1
- set_pipeline_parameter_from_for_loop
+ Set_Pipeline_Parameter_From_For_Loop
- /parameter_name=sequence_count
+ /PARAMETER_NAME=SEQUENCE_COUNT
- /parameter_index_start=1
+ /PARAMETER_INDEX_START=1
- /parameter_index_end=global::metric::emg_norm::&::side&cycle_count_global_max
+ /PARAMETER_INDEX_END=GLOBAL::METRIC::EMG_NORM::&::SIDE&Cycle_Count_Global_Max
- /parameter_index_step=1
+ /PARAMETER_INDEX_STEP=1
- /parameter_index_type=integer
+ /PARAMETER_INDEX_TYPE=INTEGER
  ;
  ! ---------------------------------------------------------------------
- ! create normalize signal
+ ! Create Normalize Signal
  ! ---------------------------------------------------------------------
- ! create a temporary signal which contains zeros at all frames
+ ! Create a temporary signal which contains zeros at all frames
- evaluate_expression
+ Evaluate_Expression
- /expression=current_signal * 0
+ /EXPRESSION=CURRENT_SIGNAL * 0
- /signal_types=analog
+ /SIGNAL_TYPES=ANALOG
- /signal_folder=envelope
+ /SIGNAL_FOLDER=ENVELOPE
- /signal_names=::emg_signal_list
+ /SIGNAL_NAMES=::EMG_SIGNAL_LIST
- /result_types=derived
+ /RESULT_TYPES=DERIVED
- /result_folders=emg_norm_temp
+ /RESULT_FOLDERS=EMG_NORM_TEMP
- /result_name=
+ /RESULT_NAME=
- /apply_as_suffix_to_signal_name=true
+ /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
  ;
- ! loop over every sequence
+ ! Loop over every sequence
- for_each
+ For_Each
- /iteration_parameter_name=sequence_current
+ /ITERATION_PARAMETER_NAME=SEQUENCE_CURRENT
- ! /iteration_parameter_count_name=
+ ! /ITERATION_PARAMETER_COUNT_NAME=
- /items=::sequence_count
+ /ITEMS=::SEQUENCE_COUNT
  ;
-  ! define the "current" sequence as temp_cycle
+  ! Define the "current" sequence as TEMP_CYCLE
-  event_define_event_sequence
+  Event_Define_Event_Sequence
-  /event_sequence_name=temp_cycle
+  /EVENT_SEQUENCE_NAME=TEMP_CYCLE
-  /event_sequence=&::side&cycle_sequence
+  /EVENT_SEQUENCE=&::SIDE&CYCLE_SEQUENCE
-  ! /exclude_events=
+  ! /EXCLUDE_EVENTS=
-  ! /inside_of_sequence=
+  ! /INSIDE_OF_SEQUENCE=
-  ! /offset_from_start=
+  ! /OFFSET_FROM_START=
-  ! /offset_from_end=
+  ! /OFFSET_FROM_END=
-  ! /offset_by=percent
+  ! /OFFSET_BY=PERCENT
-  /event_sequence_instance=::sequence_current
+  /EVENT_SEQUENCE_INSTANCE=::SEQUENCE_CURRENT
   ;
-  ! loop over every emg signal
+  ! Loop over every EMG Signal
-  for_each
+  For_Each
-  /iteration_parameter_name=emg_signal_current
+  /ITERATION_PARAMETER_NAME=EMG_SIGNAL_CURRENT
-  ! /iteration_parameter_count_name=
+  ! /ITERATION_PARAMETER_COUNT_NAME=
-  /items=::emg_signal_list
+  /ITEMS=::EMG_SIGNAL_LIST
   ;
-   ! for all frames during the current cycle,
+   ! For all frames during the current cycle,
-   ! set the values to the maximum of the emg signal
+   ! set the values to the maximum of the EMG signal
-   set_data_to_new_values
+   Set_Data_To_New_Values
-   /signal_types=derived
+   /SIGNAL_TYPES=DERIVED
-   /signal_folder=emg_norm_temp
+   /SIGNAL_FOLDER=EMG_NORM_TEMP
-   /signal_names=::emg_signal_current
+   /SIGNAL_NAMES=::EMG_SIGNAL_CURRENT
-   ! /signal_components=all_components
+   ! /SIGNAL_COMPONENTS=ALL_COMPONENTS
-   /result_types=derived
+   /RESULT_TYPES=DERIVED
-   /result_folders=emg_norm_temp
+   /RESULT_FOLDERS=EMG_NORM_TEMP
-   /result_suffix=
+   /RESULT_SUFFIX=
-   /event_sequence=temp_cycle
+   /EVENT_SEQUENCE=TEMP_CYCLE
-   ! /exclude_events=
+   ! /EXCLUDE_EVENTS=
-   ! /start_frame=
+   ! /START_FRAME=
-   ! /end_frame=
+   ! /END_FRAME=
-   ! /use_point_rate=true
+   ! /USE_POINT_RATE=TRUE
-   /replacement_values=metric_maximum(analog::envelope::&::emg_signal_current&,event_label::sequence::temp_cycle)
+   /REPLACEMENT_VALUES=METRIC_MAXIMUM(ANALOG::ENVELOPE::&::EMG_SIGNAL_CURRENT&,EVENT_LABEL::SEQUENCE::TEMP_CYCLE)
-   ! /threshold_high=no_data
+   ! /THRESHOLD_HIGH=NO_DATA
-   ! /threshold_low=no_data
+   ! /THRESHOLD_LOW=NO_DATA
-   ! /set_data_at_single_event=false
+   ! /SET_DATA_AT_SINGLE_EVENT=FALSE
    ;
-  end_for_each
+  End_For_Each
-  /iteration_parameter_name=emg_signal_current
+  /ITERATION_PARAMETER_NAME=EMG_SIGNAL_CURRENT
   ;
- end_for_each
+ End_For_Each
- /iteration_parameter_name=sequence_current
+ /ITERATION_PARAMETER_NAME=SEQUENCE_CURRENT
  ;
  ! ---------------------------------------------------------------------
- ! normalize emg signal
+ ! Normalize EMG Signal
  ! ---------------------------------------------------------------------
- ! divide the emg signals by the temporary signal above
+ ! Divide the EMG signals by the temporary signal above
- for_each
+ For_Each
- /iteration_parameter_name=emg_signal_current
+ /ITERATION_PARAMETER_NAME=EMG_SIGNAL_CURRENT
- ! /iteration_parameter_count_name=
+ ! /ITERATION_PARAMETER_COUNT_NAME=
- /items=::emg_signal_list
+ /ITEMS=::EMG_SIGNAL_LIST
  ;
-  evaluate_expression
+  Evaluate_Expression
-  /expression=analog::envelope::&::emg_signal_current& / derived::emg_norm_temp::&::emg_signal_current&
+  /EXPRESSION=ANALOG::ENVELOPE::&::EMG_SIGNAL_CURRENT& / DERIVED::EMG_NORM_TEMP::&::EMG_SIGNAL_CURRENT&
-  ! /signal_types=
+  ! /SIGNAL_TYPES=
-  ! /signal_folder=
+  ! /SIGNAL_FOLDER=
-  ! /signal_names=
+  ! /SIGNAL_NAMES=
-  /result_types=derived
+  /RESULT_TYPES=DERIVED
-  /result_folders=emg_norm
+  /RESULT_FOLDERS=EMG_NORM
-  /result_name=&::emg_signal_current&
+  /RESULT_NAME=&::EMG_SIGNAL_CURRENT&
-  ! /apply_as_suffix_to_signal_name=false
+  ! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
   ;
- end_for_each
+ End_For_Each
- /iteration_parameter_name=emg_signal_current
+ /ITERATION_PARAMETER_NAME=EMG_SIGNAL_CURRENT
  ;
-end_for_each
+End_For_Each
-/iteration_parameter_name=side
+/ITERATION_PARAMETER_NAME=SIDE
 ;
 </code>
-====== calling example meta-command ======
+===== Calling Example Meta-Command =====
-once the example meta-command from the download is placed in your [[visual3d:documentation:pipeline:meta_commands:meta_commands_overview|meta-command folder]], you can call the command using the following syntax:
+Once the example Meta-Command from the download is placed in your [[Visual3D:Documentation:Pipeline:Meta_Commands:Meta_Commands_Overview|Meta-Command folder]], you can call the command using the following syntax:
 <code>
-emg_norm_gait_cycle
+EMG_Norm_Gait_Cycle
-/emg_input_folder=envelope
+/EMG_INPUT_FOLDER=ENVELOPE
-/emg_output_folder=emg_norm
+/EMG_OUTPUT_FOLDER=EMG_NORM
-/r_emg_signal_list=emg_a+emg_b+emg_c
+/R_EMG_SIGNAL_LIST=EMG_A+EMG_B+EMG_C
-/r_event_sequence=rhs+rto
+/R_EVENT_SEQUENCE=RHS+RTO
-/l_emg_signal_list=emg_a_l+emg_b_l+emg_c_l
+/L_EMG_SIGNAL_LIST=EMG_A_L+EMG_B_L+EMG_C_L
-/l_event_sequence=lhs+lto
+/L_EVENT_SEQUENCE=LHS+LTO
 ;
 </code>
-  * **emg_input_folder** should be the emg signals you want to normalized
+  * **EMG_INPUT_FOLDER** should be the EMG signals you want to normalized
-  * **emg_output_folder** should be the resulting emg folder for the normalized signals
+  * **EMG_OUTPUT_FOLDER** should be the resulting EMG folder for the normalized signals
-  * **r_emg_signal_list** the list of right side emg signals to normalize to the right gait cycle
+  * **R_EMG_SIGNAL_LIST** the list of right side EMG signals to normalize to the right gait cycle
-  * **r_event_sequence** events which indicate the right gait cycle (this example normalizes to stance, but you probably want to normalize to the entire gait cycle)
+  * **R_EVENT_SEQUENCE** events which indicate the right gait cycle (this example normalizes to stance, but you probably want to normalize to the entire gait cycle)
-  * **l_emg_signal_list** the list of left side emg signals to normalize to the left gait cycle
+  * **L_EMG_SIGNAL_LIST** the list of left side EMG signals to normalize to the left gait cycle
-  * **r_event_sequence** events which indicate the left gait cycle (this example normalizes to stance, but you probably want to normalize to the entire gait cycle)
+  * **R_EVENT_SEQUENCE** events which indicate the left gait cycle (this example normalizes to stance, but you probably want to normalize to the entire gait cycle)
-}}