Differences

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

--- visual3d:documentation:pipeline:metric_commands:metric_to_fit_signal_to_line [2024/07/17 15:23] – sgranger
+++ visual3d:documentation:pipeline:metric_commands:metric_to_fit_signal_to_line [2025/10/01 19:32] (current) – [Example: Comparing Linearity of Two or More Signals:] wikisysop
@@ Line 1: / Line 1: @@
 ====== Metric To Fit Signal To Line ======
+====Overview====
-Fit a signal to a line
+This command can be used to fit a signal to a line.
 Y = mX + b
 and create Metrics for Slope (a), Intercept (b), Sigma m, Sigma b, CHI2, and Q (R^2)
+It can be found within the **Pipeline Workshop** under **Metric**.
+====Pipeline Command====
+The syntax for the function is as follows:
+<code>
+Metric_To_Fit_Signal_To_Line
+! /RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=
+/SIGNAL_TYPES=
+! /SIGNAL_FOLDER=ORIGINAL
+! /SIGNAL_NAMES=
+/SIGNAL_COMPONENTS=
+/X_SIGNAL_TYPE=FRAME_NUMBERS
+! /X_SIGNAL_FOLDER=ORIGINAL
+! /X_SIGNAL_NAME=TIME
+/X_SIGNAL_COMPONENT=0
+! /EVENT_SEQUENCE=
+! /EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+====Command Parameters====
+The following table shows the command parameters seen above and their descriptions:
+|**/RESULT_METRIC_NAME=**                                                                               |The resulting name of the metric                                                                 |
+|**/RESULT_METRIC_FOLDER=**                                                                             |The resulting folder of the metric                                                               |
+|**/SIGNAL_TYPES=**                                                                                     |The type of signal to be processed                                                               |
+|**/SIGNAL_NAMES=**                                                                                     |The name of the signal to be processed                                                           |
+|**/SIGNAL_FOLDER**                                                                                     |The folder of the signal to be processed                                                         |
+|**/SIGNAL_COMPONENT=**                                                                                 |The component of the signal to be processed                                                      |
+|**/X_SIGNAL_TYPE=**                                                                                    |The signal type for the independent variable                                                     |
+|**/X_SIGNAL_NAME=**                                                                                    |The signal name for the independent variable                                                     |
+|**/X_SIGNAL_FOLDER=**                                                                                  |The signal folder for the independent variable                                                   |
+|**/X_SIGNAL_COMPONENT=**                                                                               |The signal component for the independent variable                                                |
+|**/GENERATE_MEAN_AND_STDDEV=**                                                                         |Calculate the mean and standard deviation                                                        |
+|**/APPEND_TO_EXISTING_VALUES=**                                                                        |Append values to the existing result signal                                                      |
+====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.
 {{:MetrictoFitSignaltoLine.png}}
-==== Command ====
+The dialog box allows you to assign values to the command parameters outlined above.
+====Example Tracking Pelvis Position While Walking====
+Here, **Metric To Fit Signal To Line** is used to track the horizontal position of the pelvis during a gait trial and identify the linearity of its movement.
+The pipeline command is as follows:
 <code>
 Metric_To_Fit_Signal_To_Line
-/RESULT_METRIC_NAME= The resulting name of the metric
+/RESULT_METRIC_FOLDER=PROCESSED
-/RESULT_METRIC_FOLDER= The resulting folder of the metric
+/RESULT_METRIC_NAME=Pelvic_position_line
-/SIGNAL_TYPES= The signal type for the dependent variable
+/SIGNAL_TYPES=KINETIC_KINEMATIC
-/SIGNAL_NAMES= The signal name for the dependent variable
+/SIGNAL_FOLDER=RPV
-/SIGNAL_FOLDER= The signal folder for the dependent variable
+/SIGNAL_NAMES=CGPos
-/SIGNAL_COMPONENT= The signal component for the dependent variable
+/SIGNAL_COMPONENTS=Y
-/X_SIGNAL_TYPE= The signal type for the independent variable
+/X_SIGNAL_TYPE=FRAME_NUMBERS
-/X_SIGNAL_NAME= The signal name for the independent variable
+! /X_SIGNAL_FOLDER=ORIGINAL
-/X_SIGNAL_FOLDER= The signal folder for the independent variable
+! /X_SIGNAL_NAME=TIME
-/X_SIGNAL_COMPONENT= The signal component for the independent variable
+/X_SIGNAL_COMPONENT=0
-/GENERATE_MEAN_AND_STDDEV= Calculate the mean and standard deviation
+! /EVENT_SEQUENCE=
-/APPEND_TO_EXISTING_VALUES= Append values to the existing result signal
+! /EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
 ;
 </code>
-==== Result ====
+This command states that the Y (in this case Y is the walking direction) position of the CG of the subject's pelvis will be used to compute a linear equation that best matches the movement of the pelvis during this trial.
+**Results**
+{{:visual3d:documentation:pipeline:metric_commands:pelvis_line.png?600|}}
+The resulting signal includes 6 components:
+: Slope = 1.295153
+: Intercept = -0.487144
+: Slope Uncertainty = 0.002145
+: Intercept Uncertainty = 0.001587
+: Chi2 = 0.008558
+: R^2 Statistic = 0.999851
+The R^2 statistic indicates how closely the linear equation models the dataset. The closer the R^2 value is to 1 the more linear of a relationship present in the data. Here the pelvis cg position follows an almost perfectly linear trajectory.
+====Example: Comparing Linearity of Two or More Signals:====
+Here we use **Metric To Fit Signal To Line** to compute and compare the R^2 value of two joint signals between events and plot corresponding linear equation for each. In this example the command is used to compare the position of the distal (knee end) and proximal (hip end) ends of the thigh in the direction of progression for a running trial. We will use **Metric To Fit Signal To Line** to compare the linearity of the two ends of the femur. It is expected that the distal end will exhibit less linear movement as the knee joint has a greater ability for anterior/posterior translation than the hip joint which is fixed to the pelvis.
+First we will find the linear equations and associated values for each end of the RTH.
+<code>
+Metric_To_Fit_Signal_To_Line
+/RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=RTH_DIST_POS
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=RTH
+/SIGNAL_NAMES=DistEndPos
+/SIGNAL_COMPONENTS=Y
+/X_SIGNAL_TYPE=FRAME_NUMBERS
+! /X_SIGNAL_FOLDER=ORIGINAL
+! /X_SIGNAL_NAME=TIME
+/X_SIGNAL_COMPONENT=0
+! /EVENT_SEQUENCE=
+! /EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+<code>
+Metric_To_Fit_Signal_To_Line
+/RESULT_METRIC_FOLDER=PROCESSED
+/RESULT_METRIC_NAME=RTH_PROX_POS
+/SIGNAL_TYPES=KINETIC_KINEMATIC
+/SIGNAL_FOLDER=RTH
+/SIGNAL_NAMES=ProxEndPos
+/SIGNAL_COMPONENTS=Y
+/X_SIGNAL_TYPE=FRAME_NUMBERS
+! /X_SIGNAL_FOLDER=ORIGINAL
+! /X_SIGNAL_NAME=TIME
+/X_SIGNAL_COMPONENT=0
+! /EVENT_SEQUENCE=
+! /EXCLUDE_EVENTS=
+! /GENERATE_MEAN_AND_STDDEV=FALSE
+! /APPEND_TO_EXISTING_VALUES=FALSE
+;
+</code>
+**Results**
+Distal End:
+{{:visual3d:documentation:pipeline:metric_commands:rth_dist.png?500|}}
+Proximal End:
+{{:visual3d:documentation:pipeline:metric_commands:rth_prox.png?500|}}
+The results show that both ends of the right thigh segment follow similar linear equations with almost identical slopes (item 1) and intercepts (item 2). The main difference can be seen in the R^2 value (item 6) with the proximal end of the segment more closely aligning with the linear equation (high R^2 value), as expected.
+**Graphing Equations**
+{{:visual3d:documentation:pipeline:metric_commands:dist_vs_prox.png?600|}}
+Creating a new 2D graph in the reports tab helps to visualize the metrics we just computed. Here it can be seen that the proximal end of the thigh follows an almost perfectly linear trajectory, while the distal end line almost oscillates around the proximal line showing the variance present with each stride. See [[visual3d:tutorials:reports:visualizing_data|this tutorial for more information on plotting data in Visual3d]].
+====Notes====
 **The resulting signal has 6 components:**