====== Metric Event Count ======

====Overview====

This command creates a [[visual3d:documentation:visual3d_signal_types:metric_data_type|metric]] containing the number of [[visual3d:documentation:c3d_signal_types:event_label_data_type|events]] that occur during a specified time interval or [[visual3d:documentation:pipeline:event_commands:event_define_event_sequence|event sequence]]. This can come in use when trying to identify the frequency or number of occurrences of a certain movement pattern. You must first define this event by adding an event in your pipeline before you can count it. The **Metric Event Count** command can be found in the **Pipeline Workshop** under the **Metric** folder. 

====Pipeline Command====

The command can be found in the workshop as so:

<code>
Metric_Event_Count
! /RESULT_METRIC_FOLDER=PROCESSED
/RESULT_METRIC_NAME=
/EVENT_TO_COUNT=
! /TIME_INTERVAL=
! /EVENT_SEQUENCE=
! /EXCLUDE_EVENTS=
! /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
;
</code>

====Command Parameters====

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

|**RESULT_METRIC_FOLDER**|**The name of the result signal folder**|
|**RESULT_METRIC_NAME**|**The name of the result signal**|
|**EVENT_TO_COUNT**|**Specify the name of the event that is being counted**|
|**TIME_INTERVAL**|**The time interval over which events will be counted**|
|**EVENT_SEQUENCE**|**Defining a specific sequence of events to be counted**|
|**EXCLUDE_EVENTS**|**Defining events within the sequence to be excluded**|
|**GENERATE_COUNT_TOTAL_IN_GLOBAL**|**(True/False) counting the total occurrences of an event in the workspace**|

If the user specifies an **Event_Sequence/Exclude Sequence** then the count of the specified event includes all sequences in the file.

If **Time_Interval**, specified as a number, then a count of events within each time interval starting from time = 0 is specified as a separate frame. For example, if there were three ranges defined by the time sequence, there would be 3 frames of data in the resulting metric.

As of Visual3D v5.00.29, the user can select both an **Event_Sequence/Exclude Sequence** and a **Time_Interval** but only the first Event_Sequence is used. If the **Time_Interval** is populated (a number or expression) the start time is the first event in the event_sequence.

====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.

{{:MetricEventCountDialog.png}}


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

===== Example 1: Basic Metric Event Count =====

<code>
Select_Active_File
/FILE_NAME= ALL_FILES
! /QUERY=
;

Metric_Event_Count
/RESULT_METRIC_FOLDER=PROCESSED
/RESULT_METRIC_NAME=LON_COUNT
/EVENT_NAME=LON
/TIME_INTERVAL=
/EVENT_SEQUENCE=
/EXCLUDE_EVENTS=
/GENERATE_COUNT_TOTAL_IN_GLOBAL= TRUE
;
</code>

This command will count all events in the file and a metric value LON_COUNT will be created in the METRIC::PROCESSED folder. Since GENERATE_COUNT_TOTAL_IN_GLOBAL is set to TRUE, the total number of LON events in the workspace will be created as well. To see this value set the [[visual3d:documentation:definitions:active_files|Active File]] to [[visual3d:documentation:definitions:global_workspace|GLOBAL]] and a metric value LON_COUNT will be created in the METRIC::PROCESSED folder.

===== Example 2: Multiple Files =====

This example shows three ways the Metric_Event_Count command can be used. All three consider a set of 5 files containing the following event LHS.**

^ File ^ LHS Event Times ^
| mvc004.c3d | 0.960000 |
| | 2.240000 |
| | 3.500000 |
| mvc003.c3d | 0.980000 |
| | 2.260000 |
| | 3.560000 |
| mvc002.c3d | 1.000000 |
| | 2.260000 |
| | 3.600000 |
| mvc005.c3d | 0.920000 |
| | 2.140000 |
| | 3.360000 |

==== Example 2A: Count events across entire file ====

This example counts events on a per-file basis.

<code>
Metric_Event_Count
/RESULT_METRIC_NAME=LHS_COUNT
/RESULT_METRIC_FOLDER=PROCESSED
/EVENT_NAME=LHS
/TIME_INTERVAL=
/EVENT_SEQUENCE=
/EXCLUDE_EVENTS=
/GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
;
</code>

The result of this command will be:

<code>
mvc005.c3d
Event_Count= 3
mvc002.c3d
Event_Count= 3
mvc003.c3d
Event_Count= 3
mvc004.c3d
Event_Count= 3
Global_Event_Count= 12
</code>

==== Example 2B: Count events across entire file in time intervals ====

This example counts events according to time intervals over entire files and also calculates global counts.

<code>
Metric_Event_Count
/RESULT_METRIC_NAME=LHS_COUNT
/RESULT_METRIC_FOLDER=PROCESSED
/EVENT_NAME=LHS
/TIME_INTERVAL=1
/EVENT_SEQUENCE=
/EXCLUDE_EVENTS=
/GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
;
</code>

The result of this command will be:

<code>
mvc005.c3d
Interval= 0.000000 to 1.000000 Event_Count= 1
Interval= 1.000000 to 2.000000 Event_Count= 0
Interval= 2.000000 to 3.000000 Event_Count= 1
Interval= 3.000000 to 4.000000 Event_Count= 1
Interval= 4.000000 to 4.200000 Event_Count= 0
mvc002.c3d
Interval= 0.000000 to 1.000000 Event_Count= 0
Interval= 1.000000 to 2.000000 Event_Count= 1
Interval= 2.000000 to 3.000000 Event_Count= 1
Interval= 3.000000 to 4.000000 Event_Count= 1
Interval= 4.000000 to 4.580000 Event_Count= 0
mvc003.c3d
Interval= 0.000000 to 1.000000 Event_Count= 1
Interval= 1.000000 to 2.000000 Event_Count= 0
Interval= 2.000000 to 3.000000 Event_Count= 1
Interval= 3.000000 to 4.000000 Event_Count= 1
Interval= 4.000000 to 4.600000 Event_Count= 0
mvc004.c3d
Interval= 0.000000 to 1.000000 Event_Count= 1
Interval= 1.000000 to 2.000000 Event_Count= 0
Interval= 2.000000 to 3.000000 Event_Count= 1
Interval= 3.000000 to 4.000000 Event_Count= 1
Interval= 4.000000 to 4.380000 Event_Count= 0
Global_Event_Counts
Global_Event_Count= 3
Global_Event_Count= 1
Global_Event_Count= 4
Global_Event_Count= 4
Global_Event_Count= 0
</code>

==== Example 2C: Count events in a set number of intervals across entire file ====

This example counts events over 5 intervals from the event_sequence START+END, where START=1.0 and END=4.0 for all files.

<code>
Metric_Event_Count
/RESULT_METRIC_NAME=LHS_COUNT
/RESULT_METRIC_FOLDER=PROCESSED
/EVENT_NAME=LHS
/TIME_INTERVAL=(EVENT_LABEL::ORIGINAL::END-EVENT_LABEL::ORIGINAL::START)/5
/EVENT_SEQUENCE=START+END
/EXCLUDE_EVENTS=
/GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
;
</code>

The result for this command will be:

<code>
mvc005.c3d
Interval= 1.000000 to 1.600000 Event_Count= 0
Interval= 1.600000 to 2.200000 Event_Count= 1
Interval= 2.200000 to 2.800000 Event_Count= 0
Interval= 2.800000 to 3.400000 Event_Count= 1
Interval= 3.400000 to 4.000000 Event_Count= 0
mvc002.c3d
Interval= 1.000000 to 1.600000 Event_Count= 1
Interval= 1.600000 to 2.200000 Event_Count= 0
Interval= 2.200000 to 2.800000 Event_Count= 1
Interval= 2.800000 to 3.400000 Event_Count= 0
Interval= 3.400000 to 4.000000 Event_Count= 1
mvc003.c3d
Interval= 1.000000 to 1.600000 Event_Count= 0
Interval= 1.600000 to 2.200000 Event_Count= 0
Interval= 2.200000 to 2.800000 Event_Count= 1
Interval= 2.800000 to 3.400000 Event_Count= 0
Interval= 3.400000 to 4.000000 Event_Count= 1
mvc004.c3d
Interval= 1.000000 to 1.600000 Event_Count= 0
Interval= 1.600000 to 2.200000 Event_Count= 0
Interval= 2.200000 to 2.800000 Event_Count= 1
Interval= 2.800000 to 3.400000 Event_Count= 0
Interval= 3.400000 to 4.000000 Event_Count= 1
Global_Event_Counts
Global_Event_Count= 1
Global_Event_Count= 1
Global_Event_Count= 3
Global_Event_Count= 1
Global_Event_Count= 3
</code>