add peak velocity and peak acceleration

docs/reference/statistics.rst

@@ -80,3 +80,39 @@ Given pairs of :math:`(x, y)` cursor locations, the following statistics are cal
 
     * Normalized Area
         * (the area formed by paths) / (length of the paths)²
+
+Velocity
+--------
+
+.. figure:: images/velocity.svg
+   :alt: Velocity is defined as the rate of change of position with respect to time
+
+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 height of the screen.
+
+Given pairs of :math:`(x, y)` cursor locations, and pairs of :math:`t` timestamp, the following statistics are calculated, all in units of screen height:
+
+    * Velocity
+        * :math:`\frac{\sqrt{(x_{i+1}-x_i)^2+(y_{i+1}-y_i)^2}}{t_{i+1}-t_i}`
+        * the rate of change of position with respect to time
+
+    * Peak Velocity
+        * maximum velocity
+
+Acceleration
+-----------
+
+.. figure:: images/acceleration.png
+   :alt: Acceleration is the rate of change of the velocity of an object with respect to time
+
+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 height of the screen.
+
+Given pairs of :math:`(x, y)` cursor locations, and pairs of :math:`t` timestamp, the following statistics are calculated, all in units of screen height:
+
+    * Acceleration
+        * :math:`\frac{\sqrt{(\frac{x_{i+2}-x_{i+1}}{t_{i+2}-t_{i+1}}-\frac{x_{i+1}-x_{i}}{t_{i+1}-t_{i}})^2+(\frac{y_{i+2}-y_{i+1}}{t_{i+2}-t_{i+1}}-\frac{y_{i+1}-y`_{i}}{t_{i+1}-t_{i}})^2}}{t_{i+1}-t_i}`
+        * the rate of change of the velocity of an object with respect to time
+
+    * Peak Acceleration
+        * maximum Acceleration

src/vstt/stats.py

@@ -539,13 +539,13 @@ def _peak_acceleration(mouse_times: np.ndarray, mouse_positions: np.ndarray) ->
 
 
 def get_derivative(y: np.ndarray, x: np.ndarray) -> np.ndarray:
+    if x.size <= 1 or y.size <= 1:
+        return np.array([0])
     dy_dx = np.diff(y) / np.diff(x)
     return dy_dx
 
 
 def get_velocity(mouse_times: np.ndarray, mouse_positions: np.ndarray) -> np.ndarray:
-    if mouse_times.size == 0 or mouse_positions.size == 0:
-        return np.array([0])
     first_order_derivative = get_derivative(mouse_positions.transpose(), mouse_times)
     velocity = LA.norm(first_order_derivative, axis=0)
     return velocity
@@ -554,8 +554,6 @@ def get_velocity(mouse_times: np.ndarray, mouse_positions: np.ndarray) -> np.nda
 def get_acceleration(
     mouse_times: np.ndarray, mouse_positions: np.ndarray
 ) -> np.ndarray:
-    if mouse_times.size == 0 or mouse_positions.size == 0:
-        return np.array([0])
     first_order_derivative = get_derivative(mouse_positions.transpose(), mouse_times)
     second_order_derivative = get_derivative(first_order_derivative, mouse_times[:-1])
     acceleration = LA.norm(second_order_derivative, axis=0)

tests/test_stats.py

@@ -187,6 +187,18 @@ def test_peak_velocity() -> None:
         ),
         [10],
     )
+    assert np.allclose(
+        vstt.stats._peak_velocity(np.array([0.5]), np.array([[0, 0]])),
+        [0],
+    )
+    assert np.allclose(
+        vstt.stats._peak_velocity(np.array([0.5]), np.array([])),
+        [0],
+    )
+    assert np.allclose(
+        vstt.stats._peak_velocity(np.array([]), np.array([[0, 0]])),
+        [0],
+    )
 
 
 def test_peak_acceleration() -> None:
@@ -206,3 +218,15 @@ def test_peak_acceleration() -> None:
         ),
         [103.07764],
     )
+    assert np.allclose(
+        vstt.stats._peak_acceleration(np.array([0.5]), np.array([[0, 0]])),
+        [0],
+    )
+    assert np.allclose(
+        vstt.stats._peak_acceleration(np.array([0.5]), np.array([])),
+        [0],
+    )
+    assert np.allclose(
+        vstt.stats._peak_acceleration(np.array([]), np.array([[0, 0]])),
+        [0],
+    )