====== Metric Sum ======

====Overview====

The **Metric_Sum** command will sum the signal components over a range from a Start event to End event. It can be found in the **Pipeline Workshop** under **Metric**.

====Pipeline Command====

The command syntax is as follows:

<code>
Metric_Sum
! /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
! /GENERATE_MEAN_AND_STDDEV_ACROSS_SUBJECTS=FALSE
! /APPEND_TO_EXISTING_VALUES=FALSE
;
</code>

====Command Parameters====

The following table shows the command parameters seen above and their descriptions:

|**Metric_Sum**                                                                                         |                                                                                                 |
|**/Signal_Types=**                                                                                     |The type of signal to be processed                                                               |
|**/Signal_Names=**                                                                                     |The name of the signal to be processed                                                           |
|**/Signal_Folder**                                                                                     |The folder of the signal to be processed                                                         |
|**/Signal_Components=**                                                                                |The component of the signal to be processed                                                      |
|**/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Event_Sequence|Event_Sequence]]=**  |The Start and End labels                                                                         |
|**/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Exclude_Events|Exclude_Events]]=**  |Exclude ranges containing this event                                                             |
|**/[[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                              |
|**/Result_Metric_Name=**                                                                               |The name of the resulting signal                                                                 |
|**/Result_Metric_Folder=**                                                                             |The folder of the resulting signal.                                                              |
|**/Apply_As_Suffix_To_Signal_Name=**                                                                   |Apply a suffix to the Signal_Name                                                                |
|**/Generate_Mean_And_STDDEV=**                                                                         |Generate the mean and standard deviation both within each active file and across all active files|
|**/Append_To_Existing_Values=**                                                                        |Append the results to an existing signal.                                                        |
|**;**                                                                                                  |                                                                                                 |

====Dialog====

The command can be edited in a text editor or in a dialog form. To edit in the dialog pop up form either click on the **Edit** button in the pipeline workshop or double-click on the pipeline command. The dialog is shown below.

{{:Metric_Sum.jpg}}


The dialog box allows you to assign values to the command parameters outlined above.

==== Metric Sum Examples ====
In the example below the **Metric Sum** command is used to find the total work done by the right ankle by summing positive and negative work done between events.

<code>
! Compute positive and negative work for each range of positive power.
!**********************************************************************
 
! Calculate right ankle positive work by time integration of right ankle power from 
! PowerPos event to PowerNeg event 
Metric_Integrate
/Signal_Types=LINK_MODEL_BASED
/Signal_Names=Right Ankle Power
/Signal_Folder=ORIGINAL
/Signal_Components=X
/Event_Sequence=PowerPos+PowerNeg
/Exclude_Events=
/Metric_Name=Right Ankle Positive Work
/Apply_As_Suffix_To_Signal_Name=FALSE
/Generate_Mean_And_STDDEV=FALSE
/Append_To_Existing_Values=FALSE
;

! Calculate right ankle negative work by time integration of right ankle power
! from PowerNeg event to PowerPos event
Metric_Integrate
/Signal_Types=LINK_MODEL_BASED
/Signal_Names=Right Ankle Power
/Signal_Folder=ORIGINAL
/Signal_Components=X
/Event_Sequence=PowerNeg+PowerPos
/Exclude_Events=
/Metric_Name=Right Ankle Negative Work
/Apply_As_Suffix_To_Signal_Name=FALSE
/Generate_Mean_And_STDDEV=FALSE
/Append_To_Existing_Values=FALSE
;

!************************************************************************
! Compute the total positive and total negative work by summing the work.
!************************************************************************

!Compute total positive work for the right ankle 
Metric_Sum
/Signal_Types=METRIC
/Signal_Names=Right Ankle Positive Work
/Signal_Folder=PROCESSED
/Signal_Components=X
/Event_Sequence=
/Exclude_Events=
/Metric_Name=Right Ankle Total Positive Work
/Apply_As_Suffix_To_Signal_Name=FALSE
/Generate_Mean_And_STDDEV=FALSE
/Append_To_Existing_Values=FALSE
;

!Compute total negative work for the right ankle
Metric_Sum
/Signal_Types=METRIC
/Signal_Names=Right Ankle Negative Work
/Signal_Folder=PROCESSED
/Signal_Components=X
/Event_Sequence=
/Exclude_Events=
/Metric_Name=Right Ankle Total Negative Work
/Apply_As_Suffix_To_Signal_Name=FALSE
/Generate_Mean_And_STDDEV=FALSE
/Append_To_Existing_Values=FALSE
;
</code>

The result should look similar to this:

{{:visual3d:documentation:pipeline:metric_commands:rankle_work.png?600|}}

  - An example of the command **Metric_Sum** is found [[Visual3D:Documentation:Pipeline:Expressions:Expressions_Overview#Example:_Value_of_signal_at_an_analog_frame|here]]. This script uses metric_sum command to find a signal value at the analog frame rate. For details go to the page.
  - An example can be found on [[Visual3D:Documentation:Statistics:Compute_Linear_Regression#Linear_Regression_Explicit_Meta-Command|Statistics Example 4#Linear_Regression_Explicit Meta-Command]] where the meta-command uses the **Metric_Sum** command to calculate a linear regression.
  - Another example can be found on [[Visual3D:Documentation:Statistics:Meta_Command_for_Linear_Regression#Linear_Regression_with_Events_Meta-Command|Statistics Example 5#Linear Regression with Events Meta-Command]] where the meta-command uses the **Metric_Sum** command to calculate a linear regression.