====== Metric Time Between Events ======

Computes the time between events (or start and end of a sequence of events) as a metric.

**Note:** In cases where the maximum event is located at the start event (time between=0), the command metric_time_between_events will not allow zero time. This is because there could be multiple instances for that event and Visual 3D would not know which instance of that event to use for the calculation. A workaround can be found here [[Visual3D:Tutorials:Pipeline:Advanced_Pipeline_Commands#Metric_Time_Between_Events|Tutorial:_Advanced_Command_Pipeline#Metric_Time_Between_Events]]

==== Metric_Time_Between_Events Command Details ====

Below are the details for this command:

|**Metric_Time_Between_Events**                                                                       |                                                                                        |
|**/RESULT_METRIC_NAME==**                                                                            |The name of the metric signal                                                           |
|**! /RESULT_METRIC_FOLDER=PROCESSED**                                                                |The metric signal folder for the result.                                                |
|**/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Event_Sequence|Event_Sequence]]=**|A list of events (separated by "+" signs).                                              |
|**/[[Visual3D:Documentation:C3D_Signal_Types:EVENT_LABEL_Data_Type#Exclude_Events|Exclude_Events]]=**|This Event_Sequence must not be during the sequence requested.                          |
|**! /Generate_Mean_And_StdDev=TRUE**                                                                 |(True or False)Generate the mean and standard deviation for all of the metrics created  |
|**! /Append to Existing Values=FALSE**                                                               |(True or False)Append this list of metrics to an existing metric of the same result name|

\\
In this example, consider the metric **Right_Terminal_Double_Limb_Support** which is the time between **LHS** and **RTO**.

<code>
Metric_Time_Between_Events
/RESULT_METRIC_NAME=Right_Terminal_Double_Limb_Support
! /RESULT_METRIC_FOLDER=PROCESSED
/EVENT_SEQUENCE=LHS+RTO
/EXCLUDE_EVENTS=LTO+RHS
! /GENERATE_MEAN_AND_STDDEV=TRUE
! /APPEND_TO_EXISTING_VALUES=FALSE
;
</code>

Below is the dialog that pops up when pipeline selection is edited by double clicking with the left mouse button.

{{:TimeBetweenEventsDlg.png}}

**Note: Event_Sequence** - It is important to note that this command assumes that the events are specified in the correct order chronologically.

For example, if the event sequence is

E1+E2
E1 must occur before E2 or no metric signal will be created.

If it is not always possible to ensure the chronological order, a series of Pipeline Commands may be necessary.

==== Example 1 : There is only one occurrence of E1 and E2 ====

Execute the **Metric_Time_Between_Events** twice in succession, once with the range E1+E2, then the second one with the range E2+E1 and set the option /APPEND_TO_EXISTING_VALUE=TRUE on the second call.

<code>
Metric_Time_Between_Events
/RESULT_METRIC_NAME=DIFF
! /RESULT_METRIC_FOLDER=PROCESSED
/EVENT_SEQUENCE=E1+E2
/EXCLUDE_EVENTS=
/GENERATE_MEAN_AND_STDDEV=FALSE
! /APPEND_TO_EXISTING_VALUES=FALSE
;

Metric_Time_Between_Events
/RESULT_METRIC_NAME=DIFF
! /RESULT_METRIC_FOLDER=PROCESSED
/EVENT_SEQUENCE=E2+E1
/EXCLUDE_EVENTS=
/GENERATE_MEAN_AND_STDDEV=FALSE
/APPEND_TO_EXISTING_VALUES=TRUE
;
</code>

**Note:** If there are multiple events, and they can occur in any sequence, then there would be no way of telling which sequence you really wanted. If this is the case, you would need to add an event in the middle of the sequence to be explicit about which sequences that you really want, such as

E1+MID+E2, and
E2+MID+E1
==== Example 2 : There is always the same number of occurrences of E1 and E2 ====

An alternative to the **Metric Time Between Events** would be to use the command **Evaluate_Expression**. In this case you can use **Evaluate_Expression** to compute the time differences between E2 and E1.

<code>
Evaluate_Expression
/EXPRESSION=EVENT_LABEL::ORIGINAL::E2-EVENT_LABEL::ORIGINAL::E1
/RESULT_NAME=DIFF
/RESULT_TYPE=METRIC
! /RESULT_FOLDER=PROCESSED
;
</code>

==== Visual3D Versions supporting Subject Prefixes ====

NOTE: When using events in a command, the commands will iterate across subjects contained in the current workspace. As such, events and sequences listed as command parameters should NOT contain a prefix. As each subject is processed, the event range/sequence specified will automatically use the specific events prefixed for each subject as they are processed.