Statistics at peak velocity (#267)

* add statistics at peak velocity * add statistics at peak velocity * refactor code * refactor code * refactor code * change None to np.nan * reformation by mypy * use tuple instead of Tuple for type * remove commented out code --------- Co-authored-by: Liam Keegan <[email protected]>
ssciwr · Mar 6, 2024 · 100fbbd · 100fbbd
1 parent 9f45260
commit 100fbbd
Show file tree

Hide file tree

Showing 12 changed files with 518 additions and 36 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -47,6 +47,7 @@ repos:
             --ignore-missing-imports,
             --disallow-untyped-defs,
             --warn-redundant-casts,
+            --no-namespace-packages,
           ]
 
   - repo: https://github.com/rhysd/actionlint

diff --git a/docs/reference/images/RMSE_movement.png b/docs/reference/images/RMSE_movement.png
diff --git a/docs/reference/images/movement_distance.png b/docs/reference/images/movement_distance.png
diff --git a/docs/reference/images/peak.png b/docs/reference/images/peak.png
diff --git a/docs/reference/statistics.rst b/docs/reference/statistics.rst
@@ -134,3 +134,31 @@ Given pairs of :math:`(x, y)` cursor locations,the following statistics are calc
 
     * Spatial Error to central target
         * the distance between the end point of the movement to the center of the central target - radius of central target
+
+
+Statistics at peak velocity
+---------------------------
+
+.. figure:: images/peak.png
+   :alt: the statistics include movement time, total time, movement distance, RMSE movement at peak velocity
+
+The cursor location at a timestamp is given by a pair of :math:`(x, y)` coordinates,
+where :math:`(0, 0)` corresponds to the center of the screen, and 1 in these units is equal to the screen height.
+
+Given pairs of :math:`(x, y)` cursor locations,the following statistics are calculated, all in units of screen height:
+
+    * Movement time
+        * :math:`t_{peak} - t_{move}`
+        * Time from first cursor movement to the movement at peak velocity
+
+    * Total time
+        * :math:`t_{peak} - t_{display}`
+        * Time from target being displayed to the movement at peak velocity
+
+    * Movement distance
+        * .. figure:: images/movement_distance.png
+        * Euclidean point-to-point distance travelled from first cursor movement to the peak velocity
+
+    * RMSE movement
+        * .. figure:: images/RMSE_movement.png
+        * Root Mean Square Error (RMSE) of the perpendicular distance from the peak velocity mouse point to the straight line that intersects the first mouse location and the target.
diff --git a/src/vstt/display.py b/src/vstt/display.py
@@ -27,6 +27,10 @@ def default_display_options() -> vstt.vtypes.DisplayOptions:
         "peak_acceleration": False,
         "to_target_spatial_error": False,
         "to_center_spatial_error": False,
+        "movement_time_at_peak_velocity": False,
+        "total_time_at_peak_velocity": False,
+        "movement_distance_at_peak_velocity": False,
+        "rmse_movement_at_peak_velocity": False,
         "averages": True,
     }
 
@@ -55,6 +59,10 @@ def display_options_labels() -> dict[str, str]:
         "peak_acceleration": "Statistic: maximum acceleration during cursor movement",
         "to_target_spatial_error": "Statistic: distance from the movement end point to the target",
         "to_center_spatial_error": "Statistic: distance from the movement end point to the center",
+        "movement_time_at_peak_velocity": "Statistic: movement time to the point at the peak velocity",
+        "total_time_at_peak_velocity": "Statistic: total time to the point at the peak velocity",
+        "movement_distance_at_peak_velocity": "Statistic: movement distance to the point at the peak velocity",
+        "rmse_movement_at_peak_velocity": "Statistic: RMSE movement to the point at the peak velocity",
         "averages": "Also show statistics averaged over all targets",
     }