Differences

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

--- visual3d:documentation:pipeline:metric_commands:metric_compute_temporal_distance [2024/11/15 18:51] – [Files for computing temporal distances] wikisysop
+++ visual3d:documentation:pipeline:metric_commands:metric_compute_temporal_distance [2025/09/23 19:10] (current) – [Examples] wikisysop
@@ Line 1: / Line 1: @@
 ====== Metric Compute Temporal Distance ======
-Compute the [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait|Gait Temporal Distance]] values consistent with the Visual3D report item
+====Overview====
-Note that the results consist of data from multiple files, so the results are stored in the [[Visual3D:Documentation:Definitions:Global_Workspace|Global_Workspace]].
+This pipeline computes the [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait|Gait Temporal Distance]] values consistent with the Visual3D report item. Note that the results consist of data from multiple files, so the results are stored in the [[Visual3D:Documentation:Definitions:Global_Workspace|Global_Workspace]]. As with most other pipeline commands, this command acts on the [[Visual3D:Documentation:Definitions:Active_Files|Active_Files]]. Compute Temporal Distance might be used when computing stride length, or other similar values.
-The command acts on the [[Visual3D:Documentation:Definitions:Active_Files|Active_Files]].
 If, for example, you have two groups of files (e.g. 2 TAGS) and you want to compute temporal distance metrics independently for each group.
@@ Line 13: / Line 11: @@
 ===== Pipeline Command =====
-Command including default values.
+Command including default values. This command can be found in the **Pipeline Workshop** within the **Metric** folder.
 <code>
@@ Line 73: / Line 71: @@
 /TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
-===== Temporal Distance Dialog =====
-|**Version 4 & Earlier:**\\ {{:GaitTemporalDistancePropertiesDlg.gif}}  |**Version 5:**\\ {{:EditTemporalDistancev5.png}}  |
+====Command Parameters====
-==== Files for computing temporal distances ====
+The following table shows the command parameters seen above and their descriptions:
-|{{:EditTemporalDistancev5_FILES2.png}}  |- The default command will create average temporal distance values for the ACTIVE files and results can be found in the GLOBAL workspace\\ - **Calculate For Each File:** Calculate average values across entire trial\\- **Calculate For All Cmo Globals:** Calculate global average \\ - **Create All Instances:** value for each sequence (multiple values per trial)\\ \\ **NOTE:** To use the Calculate For Each File option, Calculate for Each Trial must be selected as well.  |
+|**GLOBAL_RESULT_METRIC_FOLDER**|**Name of metric result folder**|
+|**CALCULATE_PER_FILE**|**Calculate average values across entire trial**|
+|**CALCULATE_PER_ALL_CMO_GLOBALS**|**Calculate global average**|
+|**CREATE_ALL_INSTANCES**|**value for each sequence (multiple values per trial)**|
+|**CREATE_EMPTY_VALUES**|****|
+|**RIGHT/LEFT_FOOT_LOCATION**|**Signal/marker defining foot location**|
+|**HEIGHT**|**Signal type and name defining height**|
+|**---_EVENT**|**Event signal names for foot on/off**|
+|**STRICT_EVENT_SEQUENCE_VALIDATION**|**---**|
+|**R/LSTRIDE_EXCLUDE**|**Excluding right or left side of stride**|
+|**INCLUDE/EXCLUDE_EVENTS**|**Including or excluding certain events in command**|
+|**EVENT_INSTANCE**|**Which instance of an event to use**|
+|**COMPUTE_--------**|**Which values to be computed or excluded**|
+|**TREADMILL_SPEED**|**Speed of treadmill used for recording (if applicable)**|
+|**TREADMILL_DIRECTION**|**Direction of treadmill used for recording (if applicable)**|
-|{{:EditTemporalDistancev5_Signal.jpg}}  |- If the user would like to define temporal distance metrics using a signal other than the default signal (such as the proximal end of the foot), the user can select a different signal (such as the heel target).\\ \\ - The height is used to calculate [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait#Statures.2FSecond|statures/second]]  |
+===== Temporal Distance Dialog =====
-|{{:EditTemporalDistancev5_PROPERTIES.png}}  |- The event labels may be changed to any events desired.\\ \\ - Selecting **Strict Event Label Sequence** will create temporal distance measures for events that occur within a gait cycle. For example Swing Time which occurs between RTO and RHS will only be calculated if the event sequence is RHS+RTO+RHS.\\- **[SIDE} String Exclude** will exclude event sequences with that event.\\ \\ - Explanations of the calculations of the temporal distance items can be found [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait|here]].  |
+The below dialog has been used within Visual3D as of v5.
+^ Dialog ^ Description ^
+|{{:EditTemporalDistancev5_FILES2.png}}  |- The default command will create average temporal distance values for the ACTIVE files and results can be found in the GLOBAL workspace\\ - **Calculate For Each File:** Calculate average values across entire trial\\- **Calculate For All Cmo Globals:** Calculate global average \\ - **Create All Instances:** value for each sequence (multiple values per trial)\\ \\ **NOTE:** To use the Calculate For Each File option, Calculate for Each Trial must be selected as well.  |
+|{{:EditTemporalDistancev5_Signal.jpg}}  |- If the user would like to define temporal distance metrics using a signal other than the default signal (such as the proximal end of the foot), the user can select a different signal (such as the heel target).\\ \\ - The height is used to calculate [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait#Statures.2FSecond|statures/second]]  |
+|{{:EditTemporalDistancev5_PROPERTIES.png}}  |- The event labels may be changed to any events desired.\\ \\ - Selecting **Strict Event Label Sequence** will create temporal distance measures for events that occur within a gait cycle. For example Swing Time which occurs between RTO and RHS will only be calculated if the event sequence is RHS+RTO+RHS.\\- **[SIDE} String Exclude** will exclude event sequences with that event.\\ \\ - Explanations of the calculations of the temporal distance items can be found [[Visual3D:Documentation:Pipeline:Metric_Commands:Temporal_Distance_Calculations_for_Gait|here]].  |
 |{{:EditTemporalDistancev5_RANGE.jpg}}  |- **Event Instance:** 0 indicates all instances, 1 indicates the first event sequence\\ \\ - **Exclude Sequence:** Creating an event BAD would exclude the trial during which the event occurred  |
+|{{:EditTemporalDistancev5_TREADMILL.jpg}}  |- The treadmill unit vector refers to the Anterior Direction of walking\\ - Speed, (left/right/average) stride and step length, and statures/second are dependent on belt speed.\\- The result folder may have any name and will be a subfolder of the METRIC folder.  |
+====Examples====
+===Simple example: Flight Time ===
+To use the **Compute Temporal Distance** command on gait cycle trials we must first identify key gait events. This can be done using the **Automatic Gait Events** command as shown below.
+<code>
+Automatic_Gait_Events
+! /FRAME_WINDOW=8
+! /USE_TPR=TRUE
+! /TPR_EVENT_INSTANCE=1
+;
+</code>
+Now that key events in the gait cycle have been identified we can use the **Compute Temporal Distance** command to compute the mean left and right flight time for each trial.
+Flight time is the average time from LTO to RHS (ensuring no LHS or RTO events occur between LTO and RHS) and RTO to LHS (ensuring no RHS or LTO events occur between RTO and LHS).
+  * Left flight time is calculated from LTO to RHS.
+  * Right flight time is calculated from RTO to LHS.
+<code>
+Metric_Compute_Temporal_Distance
+! /GLOBAL_RESULT_METRIC_FOLDER=TEMPORAL_DISTANCE
+/CALCULATE_PER_FILE=TRUE
+! /CALCULATE_PER_ALL_CMO_GLOBALS=FALSE
+! /CREATE_ALL_INSTANCES=FALSE
+! /CREATE_EMPTY_VALUES=TRUE
+! /RIGHT_FOOT_LOCATION=KINETIC_KINEMATIC::RFT::ProxEndPos
+! /LEFT_FOOT_LOCATION=KINETIC_KINEMATIC::LFT::ProxEndPos
+! /HEIGHT=METRIC::PROCESSED::HEIGHT
+/RHS_EVENT=RHS
+/LHS_EVENT=LHS
+/RTO_EVENT=RTO
+/LTO_EVENT=LTO
+! /STRICT_EVENT_SEQUENCE_VALIDATION=FALSE
+! /RSTRIDE_EXCLUDE=
+! /LSTRIDE_EXCLUDE=
+! /INCLUDE_EVENTS=
+! /EXCLUDE_EVENTS=
+/EVENT_INSTANCE=ALL
+/COMPUTE_SPEED=FALSE
+/COMPUTE_STATURES_PER_SECOND=FALSE
+/COMPUTE_STRIDE_WIDTH=FALSE
+/COMPUTE_STRIDE_LENGTH=FALSE
+/COMPUTE_CYCLE_TIME=FALSE
+/COMPUTE_STEP_LENGTH=FALSE
+/COMPUTE_STEP_TIME=FALSE
+/COMPUTE_STANCE_TIME=FALSE
+/COMPUTE_SWING_TIME=FALSE
+/COMPUTE_STEPS_PER_MINUTE=FALSE
+/COMPUTE_STRIDES_PER_MINUTE=FALSE
+/COMPUTE_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+/COMPUTE_RIGHT_INITIAL_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+/COMPUTE_RIGHT_TERMINAL_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+/COMPUTE_FLIGHT_TIME=TRUE
+! /TREADMILL_SPEED=
+! /LEFT_TREADMILL_SPEED=
+! /TREADMILL_DIRECTION=
+;
+</code>
+Once the pipeline has been executed you should see a new **TEMPORAL_DISTANCE** folder in the METRIC section of the Signals and Events tab. Within this folder you can find the mean flight time for the left and right sides.
+{{:visual3d:documentation:pipeline:metric_commands:flight_time.png?500|}}
+===Complex example: Comparing Left and Right Stride Length for treadmill trial===
+Here we will look at a gait cycle trial using data for users running on a treadmill and compare their mean stride length for the left and right sides.
+Similarly to above, we will start by using **Automatic Gait Events** to define the gait cycle.
+Next, we will use **Metric_Compute_Temporal_Distance** to compute the length of each stride for both sides, and adjust the command parameters to account for the speed of the single belt treadmill used to record the data. In this case the treadmill was moving at 1.25 m/s and the subject walking in the y-direction (0,1,0).
+<code>
+Metric_Compute_Temporal_Distance
+! /GLOBAL_RESULT_METRIC_FOLDER=TEMPORAL_DISTANCE
+/CALCULATE_PER_FILE=TRUE
+! /CALCULATE_PER_ALL_CMO_GLOBALS=FALSE
+! /CREATE_ALL_INSTANCES=FALSE
+! /CREATE_EMPTY_VALUES=TRUE
+! /RIGHT_FOOT_LOCATION=KINETIC_KINEMATIC::RFT::ProxEndPos
+! /LEFT_FOOT_LOCATION=KINETIC_KINEMATIC::LFT::ProxEndPos
+! /HEIGHT=METRIC::PROCESSED::HEIGHT
+/RHS_EVENT=RHS
+/LHS_EVENT=LHS
+/RTO_EVENT=RTO
+/LTO_EVENT=LTO
+/STRICT_EVENT_SEQUENCE_VALIDATION=TRUE
+! /RSTRIDE_EXCLUDE=
+! /LSTRIDE_EXCLUDE=
+! /INCLUDE_EVENTS=
+! /EXCLUDE_EVENTS=
+/EVENT_INSTANCE=ALL
+/COMPUTE_SPEED=FALSE
+/COMPUTE_STATURES_PER_SECOND=FALSE
+! /COMPUTE_STRIDE_WIDTH=TRUE
+! /COMPUTE_STRIDE_LENGTH=TRUE
+/COMPUTE_CYCLE_TIME=FALSE
+/COMPUTE_STEP_LENGTH=FALSE
+/COMPUTE_STEP_TIME=FALSE
+/COMPUTE_STANCE_TIME=FALSE
+/COMPUTE_SWING_TIME=FALSE
+/COMPUTE_STEPS_PER_MINUTE=FALSE
+/COMPUTE_STRIDES_PER_MINUTE=FALSE
+/COMPUTE_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+/COMPUTE_RIGHT_INITIAL_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+/COMPUTE_RIGHT_TERMINAL_DOUBLE_LIMB_SUPPORT_TIME=FALSE
+! /COMPUTE_FLIGHT_TIME=FALSE
+/TREADMILL_SPEED=1.25
+/LEFT_TREADMILL_SPEED=1.25
+/TREADMILL_DIRECTION=UNIT_VECTOR(0,1,0)
+;
+</code>
+The computed stride data can now be found in the **Metric** folder under **Temporal_Distance**.
+To compare the left and right stride lengths we will create a horizontal chart in the **Reports** tab.
+Start by adding a new page to your report, and adding **Temporal and Distance Metrics** as an item.
-|{{:EditTemporalDistancev5_TREADMILL.jpg}}  |- The treadmill unit vector refers to the Anterior Direction of walking\\ - Speed, (left/right/average) stride and step length, and statures/second are dependent on belt speed  |
+{{:visual3d:documentation:pipeline:metric_commands:temporalitem.png?400|}}
-|{{:EditTemporalDistancev5_FOLDER.jpg}}  |- The result folder may have any name and will be a subfolder of the METRIC folder.  |
+Fill out the dialog box as so:
-===== Subject computation using subject name/prefix parameters =====
+{{:visual3d:documentation:pipeline:metric_commands:temporaldialog.png?500|}}
-Visual3D is in the process of supporting multiple subjects within the same workspace, and across CMO/Z library workspaces. Older versions of Visual3D will not support the subject prefix extensions of this command.
+Click done. You should now see a bar chart comparing the left and right step length for your trial.
-When using a version of Visual3D prior to implementing multisubject support, Visual3D treats each CMO/Z file as a single subject. In this way, the temporal and distance metrics are computed in the CMO/Z GLOBAL for the subject processed within that CMO. In the same manner, when computing the temporal and distance metrics across a library of subjects, each CMO/Z is treated as a single subject and then the subject averages are computed across CMO/Z files and placed into the workspace GLOBAL for the overall mean values across subjects.
+{{:visual3d:documentation:pipeline:metric_commands:tempgraph_.png?550|}}
+===== Multisubject Support =====
-Visual3D with multisubject support extends these metric calculations to be computed for each subject that is identified in the .C3D parameters SUBJECT section. In this way, the a single CMO/Z GLOBAL will contain the computed metrics for each subject within the CMO/Z file, prefixed with the subject's prefix identifier contained in the .C3D parameters. The GLOBAL of the CMO/Z will also contain an unprefixed set of metrics for the average across the subjects contained inside the CMO/Z file.
+Versions of Visual3D more recent than v2022.08.1 support [[visual3d:documentation:definitions:multisubject|multiple subjects]] within the same workspace, and across [[visual3d:documentation:definitions:file_formats:cmz_format|CMO/Z]] library workspaces. Visual3D with multisubject support extends these metric calculations to be computed for each subject that is identified in the .C3D parameters SUBJECT section. In this way, the a single CMO/Z [[visual3d:documentation:definitions:global_workspace|GLOBAL workspace]] will contain the computed metrics for each subject within the CMO/Z file, prefixed with the subject's prefix identifier contained in the .C3D parameters. The GLOBAL workspace of the CMO/Z will also contain an unprefixed set of metrics for the average across the subjects contained inside the CMO/Z file. When working across CMO/Z files in the CMO/Z library, multisubject support for this command will treat each subject mean in each CMO/Z file as separate subject averages to be included for calculating the temporal and distance metric averages across all the subjects in the CMO/Z library.
-When working across CMO/Z files in the CMO/Z library, multisubject support for this command will treat each subject mean in each CMO/Z file as separate subject averages to be included for calculating the temporal and distance metric averages across all the subjects in the CMO/Z library.
+Older versions of Visual3D will not support the subject prefix extensions of this command and will treat each CMO/Z file as a single subject. In this way, the temporal and distance metrics are computed in the CMO/Z GLOBAL for the subject processed within that CMO. In the same manner, when computing the temporal and distance metrics across a library of subjects, each CMO/Z is treated as a single subject and then the subject averages are computed across CMO/Z files and placed into the workspace GLOBAL for the overall mean values across subjects.
 ===== Temporal Distance Control Data =====
@@ Line 109: / Line 245: @@
 |This study investigated the basic spatio-temporal gaitmeasures of 898 primary school-aged children (5–13 years) and 82 young adults (18–27 years). Participants completed 6–8 walks at preferred speed alonga GAITRite walkway whilst barefoot and whilst wearing athletic shoes or runners. Outcome measures (non-normalized and normalized) were gait speed, cadence, step and stride length, support base, single and double support, stance duration, foot angle and associated symmetry measures. Non-normalized measures of speed, step and stride length, support base and foot angle increased with age whereas cadence reduced. Normalized measures remained unchanged with age in children whereas the young adults (both conditions) exhibited a 2.3% reduction in single support, a 5.1% increase in double support and a 2.6% increase in stance duration (p < 0.0001). For the entire sample, shoes increased walking speed by 8 cm/s, step length by 5.5 cm, stride length by 11.1 cm and base of support by 0.5 cm. In contrast, foot angle and cadence reduced by 0.18 and 3.9 steps/min respectively. Shoes increased both double support (1.6%) and stance time (0.8%), whereas single support reduced by 0.8%. Symmetry remained unaffected by age. On average, measures of step and stride symmetry (combining both conditions) fell around 0.7 cm, whereas measures of symmetry for step and stance time, single and double support fell around 0.6%. Footwear significantly affected gait (p < 0.0001). Gait may not be mature by age 13. Gait is symmetrical in healthy children and young adults but may change with pathology.|
 |[[https://www.ncbi.nlm.nih.gov/labs/articles/19692245/|Reference]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 |**Lythgo N, Wilson C, Galea M(2011)**   "Basic gait and symmetry measures for primary school-aged children and young adults. II: Walking at slow, free and fast speed"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 |//Gait and Posture 33, 2011, 29-35//                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 |This study recorded basic gait data from 656 healthy primary school-aged children (5–13 years) and 81 young adults (18–27 years) whilst walking over-ground across a level walkway at varying speed. It investigated the effect of gait speed and re-examined the issue of gait maturation. Participants completed 6–8 walks at self-selected slow, free and fast speed along a GAITRite walkway whilst wearing athletic shoes. Outcome measures (non-normalized and normalized) were gait speed, cadence, step and stride length, step and stride time, support base, single and double support (%), stance duration (%), foot angle and associated symmetry measures. Compared to free speed, participants walked 24% slower for the slow speed and 30% faster for the fast speed (p < 0.0001). Both normalized and non-normalized measures of cadence, step and stride length increased with speed (p < 0.001) whereas step and stride time reduced (p < 0.001). As a percentage of the gait cycle, single support and stance duration increased with speed (p < 0.001) whereas double support reduced (p < 0.001). Foot angle was significantly less (less toe-out) for the fast speed than the free and slow speeds (p < 0.001) whereas support base was unaffected by speed. Symmetry measures were unaffected by age or speed. Step and stride symmetry differentials (combining conditions) fell around 0.8 cm, whereas symmetry differentials for step and stance time, single and double support fell around 0.7%. This information can be used by clinicians and researchers to assess the gait of children.|
-|[[https://www.ncbi.nlm.nih.gov/labs/articles/20971013/|Reference]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+|[[https://www.ncbi.nlm.nih.gov/labs/articles/20971013/|Reference]] |