Differences

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

--- visual3d:documentation:pipeline:metric_commands:metric_event_count [2024/07/17 15:46] – created sgranger
+++ visual3d:documentation:pipeline:metric_commands:metric_event_count [2025/09/23 19:38] (current) – [Example 2: Multiple Files] wikisysop
@@ Line 1: / Line 1: @@
 ====== Metric Event Count ======
-Creates a metric containing the number of events that occur in an event sequence or time interval.
+====Overview====
-**Metric_Event_Count**
+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=
-/RESULT_METRIC_FOLDER=PROCESSED
+/EVENT_TO_COUNT=
-/EVENT_NAME=
+! /TIME_INTERVAL=
-/TIME_INTERVAL=
+! /EVENT_SEQUENCE=
-/EVENT_SEQUENCE=
+! /EXCLUDE_EVENTS=
-/EXCLUDE_EVENTS=
+! /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
-/GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
+;
-**;**
+</code>
-==== Prior to Version 5.00.29 ====
-the user could select "either" an **Event_Sequence/Exclude Sequence** or a **Time_Interval**
+====Command Parameters====
-if **Event_Sequence/Exclude Sequence**
-The count of the specified Event includes all sequences in the file
-if **Time_Interval** (specified as a number)
-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.
-==== Starting in Version 5.00.29 ====
-the user can select both an **Event_Sequence/Exclude Sequence** and a **Time_Interval** but only the first Event_Sequence is used.
+The following table shows the command parameters seen above and their descriptions:
-If the **Time_Interval** is empty the command behaves as before.
-If the **Time_Interval** is populated (a number or expression) the start time is the first event in the event_sequence.
-\\
-As of Visual3Dv5.00.29 this command must be edited manually.
-==== User Dialog Starting in Version 5.01.14 ====
+|**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**|
-|In Visual3D v5.01.14 the user dialog was introduced. The command works the same as described in v5.00.29, however the user may now modify the command using the GUI interface.  |  {{:MetricEventCountDialog.png}}|
+If the user specifies an **Event_Sequence/Exclude Sequence** then the count of the specified event includes all sequences in the file.
-==== Example_1 ====
+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.
-**Select_Active_File**
+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.
-**/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
-**;**
-\\
+====Dialog====
-=== Result ===
+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.
-LON_COUNT will count all events in the file and a metric value LON_COUNT will be created in the METRIC::PROCESSED folder.
+{{:MetricEventCountDialog.png}}
-"Since GENERATE_COUNT_TOTAL_IN_GLOBAL is set to TRUE, the total number of LON events in the workspace will be created.
-To see this value set the Active File to GLOBAL and a metric value LON_COUNT will be created in the METRIC::PROCESSED folder.
+The dialog box allows you to assign values to the command parameters outlined above.
-==== Example_2 ====
-**This example shows 3 ways the Metric_Event_Count command can be used.**
+===== Example 1: Basic Metric Event Count =====
-**Consider a set of 5 files containing the following event LHS.**
+<code>
+Select_Active_File
+/FILE_NAME= ALL_FILES
+! /QUERY=
+;
-Event LHS
+Metric_Event_Count
-mvc004.c3d
+/RESULT_METRIC_FOLDER=PROCESSED
-.960000
+/RESULT_METRIC_NAME=LON_COUNT
-.240000
+/EVENT_NAME=LON
-.500000
+/TIME_INTERVAL=
-mvc003.c3d
+/EVENT_SEQUENCE=
-.980000
+/EXCLUDE_EVENTS=
-.260000
+/GENERATE_COUNT_TOTAL_IN_GLOBAL= TRUE
-.560000
+;
-mvc002.c3d
+</code>
-.000000
-.260000
+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.
-.600000
-mvc005.c3d
+===== Example 2: Multiple Files =====
-.920000
-.140000
+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.
-.360000
-=== Count events across entire file ===
+^ 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.
-**Count across the entire file**
+<code>
-**Metric_Event_Count**
+Metric_Event_Count
 /RESULT_METRIC_NAME=LHS_COUNT
 /RESULT_METRIC_FOLDER=PROCESSED
@@ Line 91: / Line 100: @@
 /EXCLUDE_EVENTS=
 /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
-**;**
+;
-**Result**
+</code>
+The result of this command will be:
+<code>
 mvc005.c3d
 Event_Count= 3
@@ Line 102: / Line 115: @@
 Event_Count= 3
 Global_Event_Count= 12
-=== Count events across entire file in time intervals ===
+</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.
-**Count across the entire file at 1 second intervals**
+<code>
-**Metric_Event_Count**
+Metric_Event_Count
 /RESULT_METRIC_NAME=LHS_COUNT
 /RESULT_METRIC_FOLDER=PROCESSED
@@ Line 113: / Line 130: @@
 /EXCLUDE_EVENTS=
 /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
-**;**
+;
-**Result**
+</code>
+The result of this command will be:
+<code>
 mvc005.c3d
 Interval= 0.000000 to 1.000000 Event_Count= 1
@@ Line 145: / Line 166: @@
 Global_Event_Count= 4
 Global_Event_Count= 0
-=== Count events in a set number of intervals across entire file ===
+</code>
-**Count over 5 intervals from the event_sequence START+END**
+==== Example 2C: Count events in a set number of intervals across entire file ====
-****
-**Where START=1.0 and END=4.0 for all files**
+This example counts events over 5 intervals from the event_sequence START+END, where START=1.0 and END=4.0 for all files.
-**Metric_Event_Count**
+<code>
+Metric_Event_Count
 /RESULT_METRIC_NAME=LHS_COUNT
 /RESULT_METRIC_FOLDER=PROCESSED
@@ Line 158: / Line 181: @@
 /EXCLUDE_EVENTS=
 /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
-**;**
+;
-**Result**
+</code>
+The result for this command will be:
+<code>
 mvc005.c3d
 Interval= 1.000000 to 1.600000 Event_Count= 0
@@ Line 190: / Line 217: @@
 Global_Event_Count= 1
 Global_Event_Count= 3
+</code>
+====Example 3: Defining and Counting Gait Events====
+Here we will use **Automatic Gait Events** to define a series of events during a gait cycle trial, and then count those events using the **Metric Event Count** command.
+Once you have loaded in a gait trial to your Visual3D, use **Automatic Gait Events** to identify the core gait events like so:
+<code>
+Automatic_Gait_Events
+! /FRAME_WINDOW=8
+! /USE_TPR=TRUE
+! /TPR_EVENT_INSTANCE=1
+;
+</code>
+Now we can use **Metric Event Count** to count the number of left heel strikes during each trial. The command should look like so:
+<code>
+Metric_Event_Count
+/RESULT_METRIC_FOLDER=PROCESSED_events
+/RESULT_METRIC_NAME=Event_Count
+/EVENT_TO_COUNT=LHS
+! /TIME_INTERVAL=
+! /EVENT_SEQUENCE=
+! /EXCLUDE_EVENTS=
+! /GENERATE_COUNT_TOTAL_IN_GLOBAL=TRUE
+;
+</code>
+A new folder containing the counts named **PROCESSED_events** can now be found within the **Metric** folder.