Differences

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

--- visual3d:documentation:pipeline:metric_commands:metric_frames_between_events [2024/07/17 15:23] – sgranger
+++ visual3d:documentation:pipeline:metric_commands:metric_frames_between_events [2025/09/24 13:43] (current) – [Complex Example: Finding time between events using frame rate] wikisysop
@@ Line 1: / Line 1: @@
 ====== Metric Frames Between Events ======
-Computes the number of frames between events (or start and end of a sequence of events) as a metric. For example, consider Right_Terminal_Double_Limb_Support.
+====Overview====
+The **Metric Frames Between Events** computes the number of frames between events (or start and end of a sequence of events) as a metric. This can be useful in determining time between events when frame rate is known. The **Metric Event Count** command can be found in the **Pipeline Workshop** under the **Metric** folder.
 **Note that the frames will be at the POINT RATE because Visual3D computes Events at POINT RATE.**
-\\
+====Pipeline Command====
+The command can be found in the workshop as so:
 <code>
-Frames_Between_Events
+Metric_Frames_Between_Events
-/Event_Sequence=    A list of events (separated by "+" signs). For example, LHS+RTO
+! /RESULT_METRIC_FOLDER=PROCESSED
-/Exclude_Events=    This Event_Sequence must not be during the sequence requested. For example, LTO_RHS
+/RESULT_METRIC_NAME=
-/Metric_Name= The name of the metric signal. For example, Right_Terminal_Double_Limb_Support
+/EVENT_SEQUENCE=
-/Generate_Mean_And_StdDev=(True or False)Generate the mean and standard deviation for all of the metrics created
+/EXCLUDE_EVENTS=
-/Append to Existing Values=(True or False)Append this list of metrics to an existing metric of the same result name
+! /GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
 </code>
-\\
+====Command Parameters====
-\\
-Dialog that pops up when pipeline selection is edited by double clicking with the left mouse button.\\
-{{:MetricTimeBtwnEventsDlg.jpg}}\\
-\\
+The following table shows the command parameters seen above and their descriptions:
-===== Example =====
+|**RESULT_METRIC_FOLDER**|**The name of the result signal folder**|
+|**RESULT_METRIC_NAME**|**The name of the result signal**|
+|**EVENT_SEQUENCE**|** A list of events (separated by "+" signs). For example, LHS+RTO**|
+|**EXCLUDE_EVENTS**|**This Event Sequence must not be during the sequence requested. For example, LTO_RHS**|
+|**GENERATE_MEAN_AND_STDDEV**|**(True or False)Generate the mean and standard deviation for all of the metrics created**|
+|**APPEND_TO_EXISTING_VALUES**|**(True or False)Append this list of metrics to an existing metric of the same result name**|
-\\
+====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.
+{{:MetricTimeBtwnEventsDlg.jpg}}
+The dialog box allows you to assign values to the command parameters outlined above.
+====Simple Example: Frames between steps====
+If you are conducting analysis on a gait trial with gait events that have been defined, you can use **Metric Frames Between Events** to find the number of frames between each stride and compare. The number of frames separating one stride from another can be an indication of stride length and/or walking speed. Use the pipeline command below to perform the operation.
+<code>
+Metric_Frames_Between_Events
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=Frames_Between_Strides
+/EVENT_SEQUENCE=LTO+RHS
+/EXCLUDE_EVENTS=
+/GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+A new metric folder containing the following data can be seen:
+{{:visual3d:documentation:pipeline:metric_commands:frames_between.png?400|}}
+====Complex Example: Finding time between events using frame rate====
+Most movement trials will provide important trial information, like capture rate, along with the data. Using this data we can calculate important values, like stride time, if they aren't already available. Here we will use **Automatic Gait Events**, **Metric Frames Between Events**, and **Divide Signals by Constant** to calculate the average time between heel strikes in a gait trial.
+First, we will use the automatic gait events command to add tags to events in the trial like heel strikes and toe offs.
+<code>
+Automatic_Gait_Events
+! /FRAME_WINDOW=8
+! /USE_TPR=TRUE
+! /TPR_EVENT_INSTANCE=1
+;
+</code>
+Now that these events have been defined we can use **Metric Frames Between Events** to determine how many frames pass between each left toe off and the next heel strike, as well as the mean.
+<code>
+Metric_Frames_Between_Events
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=Frames_Between_Strides
+/EVENT_SEQUENCE=LTO+LHS
+/EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=TRUE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+Using the capture rate of 150 frames/second for this trial (often found in the parameters folder) we can now calculate the time between each frame using **Divide Signal By Constant**. By dividing the time between each event by the capture rate (constant) we can calculate the time. This will be done for each stride as well as for the mean stride time.
+<code>
+Divide_Signal_By_Constant
+/SIGNAL_TYPES=METRIC
+/SIGNAL_FOLDER=PROCESSED
+/SIGNAL_NAMES=Frames_Between_Strides_MEAN
+/SIGNAL_COMPONENTS=ALL
+! /RESULT_TYPES=
+/RESULT_FOLDERS=Stride_Calculation
+/RESULT_NAME=Stride_Time_MEAN
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
+/CONSTANT=150
+;
+</code>
+<code>
+Divide_Signal_By_Constant
+/SIGNAL_TYPES=METRIC
+/SIGNAL_FOLDER=PROCESSED
+/SIGNAL_NAMES=Frames_Between_Strides
+/SIGNAL_COMPONENTS=ALL
+! /RESULT_TYPES=
+/RESULT_FOLDERS=Stride_Calculation
+/RESULT_NAME=Stride_Time
+/APPLY_AS_SUFFIX_TO_SIGNAL_NAME=FALSE
+/CONSTANT=150
+;
+</code>
-|<code>\\ Metric_Frames_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>  |  {{:MetricTimeBtwnEventsDlg_Example.jpg}}|
+You should now see two new folders named **Stride_Time** and **Stride_Time_MEAN** containing stride time data for each trial.
+{{:visual3d:documentation:pipeline:metric_commands:stride_time.png?500|}}
+{{:visual3d:documentation:pipeline:metric_commands:stride_time_mean.png?500|}}
 ==== Visual3D Versions supporting Subject Prefixes ====