Differences

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

--- visual3d:documentation:pipeline:signal_commands:global_normalized_signal_mean [2024/06/19 12:53] – sgranger
+++ visual3d:documentation:pipeline:signal_commands:global_normalized_signal_mean [2024/11/15 20:57] (current) – Major strides towards pipeline command format. wikisysop
@@ Line 1: / Line 1: @@
-{{{{{{{{{{this command will compute the mean signal from a collection of signal traces. each trace is time normalized to the specified event_sequence. note that the output signal is a [[visual3d:documentation:definitions:file_formats:p2d_format|p2d signal]]. the resulting signal, therefore, is stored in the global_workspace.
+===== Global Normalized Signal Mean =====
-there are options within this command for calculating means:
+This command computes the mean signal from a collection of signal traces, with each trace time-normalized to the specified [[visual3d:documentation:c3d_signal_types:event_label_data_type#event_sequence|event sequence]]. Note that the output signal is a [[Visual3D:Documentation:Definitions:File_Formats:P2D_Format|P2D Signal]] and is therefore stored in the Global Workspace.
-  * calculate the mean for all traces from all active files
+There are options within this command for calculating means:
-  * in addition to the global mean signal, the mean value is computed for all signal traces with each active file. the global mean value is then the mean value of all values across all active c3d files
+  * for all traces from all active files
-  * for more than one cmo workspace. if the cmo workspace is active (either motion files or globals then process the per cmo mean). in other words the mean value computed from the cmo library is the mean of the mean values from each cmo file. for example, if one cmo file has 10 signal traces and another cmo file has 1 signal trace, each cmo file contributes the same weight (i.e. each file contributes one mean signal trace). it is important to highlight the destinction, albeit subtle, between how this command functions when used within a single workspace and when used within the cmo library. for instance, within a single workspace the command will compute the mean for all instances in each trial and a global mean of all instances in the workspace. however, within the cmo library each cmo/cmz file contributes one mean value regardless of the number of instances within the file, and the command computes the mean of these mean values.
+  * for all Signal traces with each active file. The global mean value is then the mean value of all values across all active c3d files.
+  * for more than one CMO workspace. The mean value computed for the CMO library is the mean of the mean values from each CMZ file. For example, if one CMZ file has 10 signal traces and another CMZ file has 1 signal trace, each CMZ file contributes the same weight (i.e. each file contributes one mean signal trace).
-the details for the above command options are discussed in the next section.
+<code>
+Global_Normalized_Signal_Mean
+/SIGNAL_TYPES=LINK_MODEL_BASED+LINK_MODEL_BASED
+/SIGNAL_NAMES=RKNEE_ANGLE+LKNEE_ANGLE
+/SIGNAL_FOLDER=ORIGINAL+ORIGINAL
+/SIGNAL_COMPONENTS=X+X
+/START_LABEL=
+/END_LABEL=
+/EVENT_SEQUENCE= RHS+RHS++LHS+LHS
+! /EXCLUDE_EVENTS=
+/RESULT_NAME=KNEE_FLEXION
+! /RESULT_FOLDER=ORIGINAL
+/NORMALIZE_POINTS=101
+/CREATE_STANDARD_DEVIATION=TRUE
+! /CALCULATE_PER_FILE=FALSE
+;
+</code>
-===== pipeline command =====
-the details for the command are:
-**global_normalized_signal_mean**
-/**signal_types**=link_model_based+link_model_based
-/**signal_names**=rknee_angle+lknee_angle
-/**signal_folder**=original+original
-**/signal_components**=x+x
-**/start_label**=
-**/end_label**=
-**/event_sequence**= rhs+rhs++lhs+lhs
-**! /exclude_events**=
-**/result_name**=knee_flexion
-**! /result_folder**=original
-**/normalize_points**=101
-**/create_standard_deviation**=true
-**! /calculate_per_file**=false
-**;**
-if **calculate_per_file=false** all signal traces from all active files are used to compute the mean
-\\
+==== Parameters ====
-if **calculate_per_file=true** in addition to the global mean signal the mean value is computed for all signal traces with each active file. the global mean value is then the mean value of the mean values
-\\
+If **CALCULATE_PER_FILE=false** All signal traces from all active files are used to compute the mean
-**if the cmo workspace is active** (either motion files or globals, then process the per cmo mean). in other words the mean value computed from the cmo library is the mean of the mean values from each cmo file. for example, if one cmo file has 10 signal traces and another cmo file has 1 signal trace, each cmo file contributes the same weight (i.e. each file contributes one mean signal trace).
-===== resulting signals =====
+If **CALCULATE_PER_FILE=true** In addition to the global mean signal the mean value is computed for all Signal traces with each active file. The global mean value is then the mean value of the mean values
-the resulting signal is a [[visual3d:documentation:definitions:file_formats:p2d_format|p2d]] signal and is stored in the global_workspace.
+If the **CMO Library** is active, it is important to highlight the distinction, albeit subtle, between how this command functions when used within a single workspace and when used within the CMO library. For instance, within a single workspace the command will compute the mean for all instances in each trial and a global mean of all instances in the workspace. However, within the CMO library each CMZ file contributes one mean value regardless of the number of instances within the file, and the command computes the mean of these mean values.
-**if calculate_per_file=true** a p2d signal is also stored with each c3d file.
+==== Output ====
-===== interactive dialog =====
+The resulting signal is a [[Visual3D:Documentation:Definitions:File_Formats:P2D_Format|P2D]] signal and is stored in the Global Workspace.
-several pipeline command have an interactive dialog that will allow you to set parameters via the dialog. for some parameters, you may still have to make changes via the text editor. the dialog for global_normalized_signal_mean is found below.
+If **CALCULATE_PER_FILE=true** then a P2D signal is also stored with each C3D file.
-gmsm_1.jpg
+==== Dialog ====
-\\
+The Global_Normalized_Signal_Mean command can also be edited interactively using the following dialog
-\\
+{{:GMSM_1.jpg}}
-===== subject computation using subject name/prefix parameters =====
+==== Multisubject support ====
-visual3d is in the process of supporting multiple subjects within the same workspace, and across cmo/z library workspaces. older versions of visual3d will not support the subject prefix extensions of this command.\\
+Visual3D supports multiple subjects within the same workspace, and across CMO/Z library workspaces. Older versions of Visual3D will not support the subject prefix extensions of this command.
-\\
-when using a version of visual3d prior to implementing multisubject support, visual3d treats each cmo/z file as a single subject. in this way, the normalized signal mean curve is generated in the cmo/z global for the subject processed within that cmo. in the same manner, when computing the normalized signal mean curve across a library of subjects, each cmo/z is treated as a single subject and then the normalized signal mean is computed across cmo/z files and placed into the workspace global for the overall mean curve across subjects.\\
-\\
-visual3d with multisubject support extends these normalized signal mean calculations to be computed for each subject that is identified in the .c3d parameters subject section. in this way, the a single cmo/z global will contain the normalized mean curve for each subject within the cmo/z file, prefixed with the subject's prefix identifier contained in the .c3d parameters. the global of the cmo/z will also contain an unprefixed global normalized signal mean curve across all the subjects contained inside the cmo/z file.\\
-\\
-when working across cmo/z files in the cmo/z library, multisubject support for this command will treat each subject in each cmo/z file as separate subject to be separately included for calculating the normalized signal mean curve across all the subjects in the cmo/z library.
-\\
+When using a version of Visual3D [[visual3d:getting_started:visual3d_release_notes#major_v2022081_release|prior to v2022.08.1]], Visual3D treats each CMO/Z file as a single subject. In this way, the normalized signal mean curve is generated in the CMO/Z Global Workspace for the subject processed within that file. In the same manner, when computing the normalized signal mean curve across a library of subjects, each CMO/Z is treated as a single subject and then the normalized signal mean is computed across CMO/Z files and placed into the workspace GLOBAL for the overall mean curve across subjects.
-\\
+After v2022.08.1, Visual3D extends these normalized signal mean calculations to be computed for each subject that is identified in the .C3D parameters SUBJECT section. In this way, the a single CMO/Z GLOBAL will contain the normalized mean curve for each subject within the CMO/Z file, prefixed with the subject's prefix identifier contained in the .C3D parameters. The Global Workspace of the CMO/Z file will also contain an unprefixed global normalized signal mean curve across all the subjects contained inside the CMO/Z file. When working across CMO/Z files in the CMO/Z library, multisubject support for this command will treat each subject in each CMO/Z file as separate subject to be separately included for calculating the normalized signal mean curve across all the subjects in the CMO/Z library.
-\\
+==== Examples ====
+This command is incredibly useful for summarizing data in your CMZ files and there are a number of ways in which it can be used.
-===== examples =====
+=== Example 1: Global Normalized Means for 2 Signals ===
-below are a few examples using this command.
+This example will time-normalize a signal (in this case Knee Flexion Angle) between events (RHS to RHS) for right knee angles and (LHS to LHS) for left knee angles, and compute the Global mean and standard deviation.
-==== example 1: global normalized means for 2 signals ====
+**Note:** this example assumes that Right and Left Knee angles have been created and the events RHS and LHS have been found.
-this example will time normalize a signal (in this case knee flexion angle) between events (rhs to rhs) for right knee angles and (lhs to lhs) for left knee angles, and compute a global mean and standard deviation.
+First add the **Global_Normalized_Signal_Mean** command to the pipeline. Double click on the command to launch the dialog.
-**note:** this example assumes that right and left knee angles have been created and the events rhs and lhs have been found.
+{{:GMSM_1.jpg}}
-\\
+In the bottom left-hand section of the dialog, select the **Link_Model_Based** signal type, **RKNEE_ANGLE** signal, and **X** component. Select the event sequence (e.g **RHS** to **RHS**). Click on **Add A New Signal**. The signal will now appear in the middle section of the dialog.
-first add the **global_normalized_signal_mean** command to the pipeline. double click on the command to launch the dialog.
-gmsm_1.jpg
+{{:GNSM_2.jpg}}
-in the bottom left-hand section of the dialog, select the **link_model_based** signal type, **rknee_angle** signal, and **x** component. select the event sequence (e.g **rhs** to **rhs**). click on **add a new signal**. the signal will now appear in the middle section of the dialog.
+To add the left knee angle signal, select the **Link_Model_Based** signal type, **LKNEE_ANGLE** signal, and **X** component. Select the event sequence (e.g **LHS** to **LHS**). Click on **Add A New Signal**. The signal will now appear in the middle section of the dialog.
-gnsm_2.jpg
+{{:GNSM_3.jpg}}
-to add the left knee angle signal, select the **link_model_based** signal type, **lknee_angle** signal, and **x** component. select the event sequence (e.g **lhs** to **lhs**). click on **add a new signal**. the signal will now appear in the middle section of the dialog.
+Enter the **P2D Result Signal Name**, in this case **Knee_Angle**. Click on **Create Standard Deviation**.
-gnsm_3.jpg
+{{:GNSM_4.jpg}}
-enter the **p2d result signal name**, in this case **knee_angle**. click on **create standard deviation**.
+Click **OK** to close the dialog. The text representation of the command is similar to the example seen in the next section.
-gnsm_4.jpg
+=== Example 2: Global Normalized Means for more than two signals ===
-click **ok** to close the dialog. the text representation of the command is similar to the example seen in the next secton.
+This example will time-normalize several signals at the Hip, Knee, and Ankle for both left and right sides using a meta-command. The means for all 3 components of the each signal will be calculated.
-==== example 2: global normalized means for more than two signals ====
+Let the CMZ file contain the following signals:
+  * RANKLE_ANGLE
+  * RKNEE_ANGLE
+  * RHIP_ANGLE
+  * LANKLE_ANGLE
+  * LKNEE_ANGLE
+  * LHIP_ANGLE
-this example will time normalize several signals at the hip, knee, and ankle for both left and right sides using a meta-command. the means for all 3 components of the each signal will be calculated.
+The events for heel strike are found and labeled **LHS** and **RHS**. This pipeline command script will call the meta-command **Create_Global_Means_For_Left_Right** to calculate the mean signal from heel strike to heel strike.
-let the cmo file contain the following signals:
-**rankle_angle**
-**rknee_angle**
-**rhip_angle**
-**lankle_angle**
-**lknee_angle**
-**lhip_angle**
-the events for heel strike are found and labeled **lhs** and **rhs**. this pipeline command script will call the meta-command **create_global_means_for_left_right** to calculate the mean signal from heel strike to heel strike.
 <code>
-create_global_means_for_left_right
+Create_Global_Means_For_Left_Right
-/type=angle
+/TYPE=ANGLE
-/joints=ankle+knee+hip
+/JOINTS=ANKLE+KNEE+HIP
-/start_event=hs
+/START_EVENT=HS
-/end_event=hs
+/END_EVENT=HS
 ;
 </code>
-the meta-command **create_global_means_for_left_right** below can be copied and pasted into a text editor and should be placed in the **meta_command** folder within the **plugins** folder is as follows:
+The Meta-Command **Create_Global_Means_For_Left_Right** below can be copied and pasted into a text editor and should be placed in the **Meta_Command** folder within the **Plugins** folder is as follows:
 <code>
-! begin_meta
+! BEGIN_META
-! meta_cmd_name=create_global_means_for_left_right
+! META_CMD_NAME=Create_Global_Means_For_Left_Right
-! meta_param= type:string::yes
+! META_PARAM= TYPE:string::yes
-! meta_param= joints:string::yes
+! META_PARAM= JOINTS:string::yes
-! meta_param= start_event:string::yes
+! META_PARAM= START_EVENT:string::yes
-! meta_param= end_event:string::yes
+! META_PARAM= END_EVENT:string::yes
-! end_meta
+! END_META
-! loop for the joint angles that are passed to the meta-command
+! Loop for the joint angles that are passed to the meta-command
-for_each
+For_Each
-/iteration_parameter_name=index1
+/ITERATION_PARAMETER_NAME=INDEX1
-/items=::joints
+/ITEMS=::JOINTS
 ;
-! loop for the components - x, y, and z
+! Loop for the Components - X, Y, and Z
-for_each
+For_Each
-/iteration_parameter_name=index2
+/ITERATION_PARAMETER_NAME=INDEX2
-/items=x+y+z
+/ITEMS=X+Y+Z
 ;
-! create the global_normalized_signal_mean using the joint parameter and the type parameter for the left and right sides
+! Create the Global_Normalized_Signal_Mean using the joint parameter and the type parameter for the Left and Right sides
-global_normalized_signal_mean
+Global_Normalized_Signal_Mean
-/signal_types=link_model_based+link_model_based
+/SIGNAL_TYPES=LINK_MODEL_BASED+LINK_MODEL_BASED
-/signal_names=r&::index1&_&::type+l&::index1&_&::type
+/SIGNAL_NAMES=R&::INDEX1&_&::TYPE+L&::INDEX1&_&::TYPE
-/signal_folder=original+original
+/SIGNAL_FOLDER=ORIGINAL+ORIGINAL
-/signal_components=::index2+::index2
+/SIGNAL_COMPONENTS=::INDEX2+::INDEX2
-/start_label=r&::start_event+l&::end_event
+/START_LABEL=R&::START_EVENT+L&::END_EVENT
-/end_label=r&::start_event+l&::end_event
+/END_LABEL=R&::START_EVENT+L&::END_EVENT
-! /event_sequence=
+! /EVENT_SEQUENCE=
-! /exclude_events=
+! /EXCLUDE_EVENTS=
-/result_name=::index1&_&::type&_&::index2
+/RESULT_NAME=::INDEX1&_&::TYPE&_&::INDEX2
-! /result_folder=original
+! /RESULT_FOLDER=ORIGINAL
-! /normalize_points=101
+! /NORMALIZE_POINTS=101
-! /create_standard_deviation=false
+! /CREATE_STANDARD_DEVIATION=FALSE
-! /calculate_per_file=false
+! /CALCULATE_PER_FILE=FALSE
 ;
-! end of component loop
+! End of component loop
-end_for_each
+End_For_Each
-/iteration_parameter_name=index2
+/ITERATION_PARAMETER_NAME=INDEX2
 ;
-! end of the joint loop
+! End of the joint loop
-end_for_each
+End_For_Each
-/iteration_parameter_name=index1
+/ITERATION_PARAMETER_NAME=INDEX1
 ;
 </code>
-===== exporting the global normalized signal mean =====
+==== Exporting the Global Normalized Signal Mean ====
-the signal is stored in the **global workspace**, so it is necessary to make **global** the active file before the export command. in addition, the resulting signal is a p2d file. the components for a p2d signal are different. below is an example script that will export to ascii the resulting p2d file.
+The signal is stored in the [[visual3d:documentation:definitions:global_workspace|Global Workspace]], so it is necessary to make **GLOBAL** the active file before the export command. In addition, the resulting signal is in the [[visual3d:documentation:definitions:file_formats:p2d_format|P2D format]] which means that the components are different. Below is an example script that will export the resulting P2D file to ASCII.
 <code>
-! select global as the active
+! Select GLOBAL as the active
-select_active_file
+Select_Active_File
-/file_name= global
+/FILE_NAME= GLOBAL
-! /query=
+! /QUERY=
 ;
-! export the global normalized signal mean to ascii
+! Export the Global Normalized Signal Mean to ASCII
-! the all signal components will export the normalized time, the mean signal, and the standard deviation
+! The ALL signal components will export the normalized time, the mean signal, and the standard deviation
-! leaving the file_name blank will cause the user to be prompted for a name
+! Leaving the file_name blank will cause the user to be prompted for a name
-export_data_to_ascii_file
+Export_Data_To_Ascii_File
-/file_name=
+/FILE_NAME=
-/signal_types=p2d
+/SIGNAL_TYPES=P2D
-/signal_names=knee_angle_x
+/SIGNAL_NAMES=KNEE_ANGLE_X
-/signal_folder=original
+/SIGNAL_FOLDER=ORIGINAL
-/signal_components=all
+/SIGNAL_COMPONENTS=ALL
-! /start_label=
+! /START_LABEL=
-! /end_label=
+! /END_LABEL=
-! /event_sequence=
+! /Event_Sequence=
-! /exclude_events=
+! /Exclude_Events=
-! /use_point_rate=false
+! /USE_POINT_RATE=FALSE
-! /normalize_data=false
+! /NORMALIZE_DATA=FALSE
-! /normalize_points=101
+! /NORMALIZE_POINTS=101
-! /export_mean_and_std_dev=false
+! /EXPORT_MEAN_AND_STD_DEV=FALSE
-! /use_p2d_format=false
+! /USE_P2D_FORMAT=FALSE
 ;
 </code>
-}}}}}}}}}}