Differences

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

--- visual3d:documentation:pipeline:metric_commands:metric_mean [2024/06/19 13:37] – removed sgranger
+++ visual3d:documentation:pipeline:metric_commands:metric_mean [2024/11/22 19:00] (current) – wikisysop
@@ Line 1: / Line 1: @@
+====== Metric Mean ======
+This command computes the Mean Value of a Signal and stores the value as a metric.
+===== Command Syntax =====
+The syntax for the function is as follows:
+<code>
+Metric_Mean
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=
+! /APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
+/SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+! /COMPONENT_SEQUENCE=
+/EVENT_SEQUENCE=
+/EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+===== Parameters=====
+The Parameters for the function is as follows:
+|**Metric_Mean**                                                                                              |                                                                                             |
+|/RESULT_METRIC_NAME=                                                                                         |The name of the metric signal created                                                        |
+|!/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE                                                                       |Add a suffix to the signal name                                                              |
+|!/RESULT_METRIC_FOLDER=PROCESSED                                                                             |                                                                                             |
+|/SIGNAL_TYPES=TARGET                                                                                         |                                                                                             |
+|/SIGNAL_NAMES=                                                                                               |Signal                                                                                       |
+|/SIGNAL_FOLDER=ORIGINAL                                                                                      |                                                                                             |
+|/SIGNAL_COMPONENTS=ALL_COMPONENTS                                                                            |Signal Components                                                                            |
+|/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Event_Sequence|EVENT_SEQUENCE]]=            |Specify the sequence of Events. Any number of Events can be entered (separated by +).        |
+|                                                                                                             |This specific sequence of events must be true for a metric to be computed.                   |
+|                                                                                                             |The metric is computed from the first event in the sequence to the last event in the sequence|
+|**/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Exclude_Events|EXCLUDE_EVENTS]]=**        |If this event occurs between the first and last event, do not computed a metric              |
+|**/[[Visual3D:Documentation:Pipeline:Metric_Commands:SEQUENCE_PERCENT_START|SEQUENCE_PERCENT_START]]=**      |Within the event sequence specify the beginning of the range as a percent                    |
+|**/[[Visual3D:Documentation:Pipeline:Metric_Commands:SEQUENCE_PERCENT_START|SEQUENCE_PERCENT_END]]=**        |Within the event sequence specify the end of the range as a percent                          |
+|! /[[Visual3D:Documentation:Pipeline:Signal_Commands:GENERATE_MEAN_AND_STDDEV|Generate_Mean_and_Stddev]]=TRUE|Generate the mean and standard deviation of this metric across ranges and files              |
+|! /APPEND_TO_EXISTING_VALUES=FALSE                                                                           |Metrics can replace an existing signal or be appended to it.                                 |
+==== Example: Include and Exclude Ranges ====
+In the following example, compute the Mean Value of the signal **RKNEE_ANGLE** from **RHS** to **RHS**. The dialog of the command is:
+{{:Metric_Mean1.jpg}}
+The associated pipeline command text is:
+<code>
+Metric_Mean
+/RESULT_METRIC_NAME=_MEAN
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
+! /RESULT_METRIC_FOLDER=PROCESSED
+/SIGNAL_TYPES=LINK_MODEL_BASED
+/SIGNAL_NAMES=RKNEE_ANGLE
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_COMPONENTS=ALL_COMPONENTS
+/EVENT_SEQUENCE=RHS+RHS
+/EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+Executing the command will result in:
+  * Two metric signals in the **METRIC::PROCESSED FOLDER** in each file,
+    * **RKNEE_ANGLE_MEAN** - the mean value for each RANGE in the file
+    * **RKNEE_ANGLE_MEAN_MEAN** - the mean value for all ranges
+  * Two metric signals in the **GLOBAL_WORKSPACE**
+    * **RKNEE_ANGLE_MEAN_MEAN** - the mean value for all ranges for all files that were active
+    * **RKNEE_ANGLE_MEAN_STDDEV** - the standard deviation of the mean values for all ranges.
+An example of results is shown below:
+{{:Metric_Mean2.jpg}}
+If, for example, we did not want to include the first gait cycle in the file file 'OG_RA_run01.c3d' in this list we can add an **Event_Label** called **BAD** to the file between **RHS** and **RHS**.
+{{:Metric_Mean3.jpg}}
+In the image above, the two blue lines indicate the **RHS** event. Add an Event Label named **BAD** manually by double clicking on the signal line.
+The metric_mean command can be modified as follows:
+{{:Metric_Mean4.jpg}}
+which indicates that a range of data containing the label **BAD** should not be included. The result of executing the pipeline command is now:
+{{:Metric_Mean5.jpg}}
+**NOTE:** When you run a metric command, and tell it to create a global mean, it uses all the individual ranges to compute the overall mean (ie. one trial has 4 ranges, second trial has 1 range, the global mean is generated from the 5 values).
+Each trial will have a mean and then a mean of those means. If you select ALL_FILES as the active file and view the metric, you will see the means of the individual trial ranges and the mean of the means within that trial. The GLOBAL will show the overall mean (mean of all the means).
+===== Example: Metric Mean of Metric signals at Initial Contact =====
+This script will take the mean of Left at Right Knee angles at Initial contact (LON and RON)
+<code>
+! Get the initial contact value of LKNEE_ANGLE at LON
+Metric_Signal_Value_At_Event
+/RESULT_METRIC_NAME=Knee_Angle_IC
+! /RESULT_METRIC_FOLDER=PROCESSED
+/SIGNAL_TYPES=LINK_MODEL_BASED
+/SIGNAL_NAMES=LKNEE_ANGLE
+! /SIGNAL_FOLDER=ORIGINAL
+/EVENT_NAME=LON
+/GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+! /GENERATE_VECTOR_LENGTH_METRIC=FALSE
+! /RETAIN_NO_DATA_VALUES=FALSE
+;
+! Get the initial contact value of RKNEE_ANGLE at RON and concatenate this with the previous metric
+Metric_Signal_Value_At_Event
+/RESULT_METRIC_NAME=Knee_Angle_IC
+! /RESULT_METRIC_FOLDER=PROCESSED
+/SIGNAL_TYPES=LINK_MODEL_BASED
+/SIGNAL_NAMES=RKNEE_ANGLE
+! /SIGNAL_FOLDER=ORIGINAL
+/EVENT_NAME=RON
+/GENERATE_MEAN_AND_STDDEV=FALSE
+/APPEND_TO_EXISTING_VALUES=TRUE
+! /GENERATE_VECTOR_LENGTH_METRIC=FALSE
+! /RETAIN_NO_DATA_VALUES=FALSE
+;
+! Compute the mean and standard deviation of these values.
+Metric_Mean
+/RESULT_METRIC_NAME=_MEAN
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=TRUE
+! /RESULT_METRIC_FOLDER=PROCESSED
+/SIGNAL_TYPES=METRIC
+/SIGNAL_NAMES=Knee_Angle_IC
+/SIGNAL_FOLDER=PROCESSED
+! /SIGNAL_COMPONENTS=ALL_COMPONENTS
+/EVENT_SEQUENCE=
+/EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>