Implement configuration module and utility functions for reference spiral generation, including logger setup. Refactor velocity metrics calculations to improve clarity and add median metrics. Update tests to cover all velocity types and reflect changes in function names and expected values.

Author: alperkent

src/graphomotor/core/config.py

@@ -0,0 +1,33 @@
+"""Configuration module for Graphomotor."""
+
+import logging
+
+import numpy as np
+
+
+class _SpiralConfig:
+    """Configuration for the reference spiral generation."""
+
+    SPIRAL_CENTER_X = 50
+    SPIRAL_CENTER_Y = 50
+    SPIRAL_START_RADIUS = 0
+    SPIRAL_GROWTH_RATE = 1.075
+    SPIRAL_START_ANGLE = 0
+    SPIRAL_END_ANGLE = 8 * np.pi
+    SPIRAL_NUM_POINTS = 10000
+
+
+def get_logger() -> logging.Logger:
+    """Get the Graphomotor logger."""
+    logger = logging.getLogger("graphomotor")
+    if logger.hasHandlers():
+        return logger
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - "
+        "%(filename)s:%(lineno)s - %(funcName)s - %(message)s",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger

src/graphomotor/features/velocity.py

@@ -6,7 +6,7 @@
 from graphomotor.core import models
 
 
-def _get_velocity_metrics(velocity: np.ndarray, type_: str) -> dict[str, float]:
+def _get_velocity_statistics(velocity: np.ndarray, type_: str) -> dict[str, float]:
     """Calculate velocity metrics for a given type of velocity.
 
     Args:
@@ -19,6 +19,7 @@ def _get_velocity_metrics(velocity: np.ndarray, type_: str) -> dict[str, float]:
     """
     return {
         f"{type_}_sum": np.sum(np.abs(velocity)),
+        f"{type_}_median": np.median(np.abs(velocity)),
         f"{type_}_variation": stats.variation(velocity),
         f"{type_}_skewness": stats.skew(velocity),
         f"{type_}_kurtosis": stats.kurtosis(velocity),
@@ -34,18 +35,17 @@ def calculate_velocity_metrics(spiral: models.Spiral) -> dict[str, float]:
         1. Linear velocity: The magnitude of change of Euclidean distance in pixels
            per second. This is calculated as the square root of the sum of squares of
            the differences in x and y coordinates divided by the difference in time.
-        2. Radial velocity: The magnitude of change of distance from center in pixels
-           per second. Radius is calculated as the square root of the sum of squares of
-           the x and y coordinates. The radial velocity is the change in radius divided
-           by the change in time.
+        2. Radial velocity: The magnitude of change of distance from center (radius) in
+           pixels per second. Radius is calculated as the square root of the sum of
+           squares of x and y coordinates.
         3. Angular velocity: The magnitude of change of angle in radians per second.
            Angle is calculated using the arctangent of y coordinates divided by x
-           coordinates. It is assumed that the drawing starts in the first quadrant
-           The angle is unwrapped to ensure continuity. The angular
-           velocity is the change in angle divided by the change in time.
+           coordinates, and then unwrapped to maintain continuity across the -π to π
+           boundary.
 
     For each velocity type, the following metrics are calculated:
-        - Sum: Sum of absolute velocity values
+        - Sum: Total absolute velocity over the entire drawing
+        - Median: Median of absolute velocity values
         - Variation: Coefficient of variation
         - Skewness: Asymmetry of the velocity distribution
         - Kurtosis: Tailedness of the velocity distribution
@@ -68,20 +68,12 @@ def calculate_velocity_metrics(spiral: models.Spiral) -> dict[str, float]:
     dr = np.diff(radius)
     dtheta = np.diff(theta)
 
-    vx = dx / dt
-    vy = dy / dt
-    linear_velocity = np.sqrt(vx**2 + vy**2)
-
+    linear_velocity = np.sqrt(dx**2 + dy**2) / dt
     radial_velocity = dr / dt
     angular_velocity = dtheta / dt
 
-    linear_velocity_metrics = _get_velocity_metrics(linear_velocity, "linear_velocity")
-    radial_velocity_metrics = _get_velocity_metrics(radial_velocity, "radial_velocity")
-    angular_velocity_metrics = _get_velocity_metrics(
-        angular_velocity, "angular_velocity"
-    )
     return {
-        **linear_velocity_metrics,
-        **radial_velocity_metrics,
-        **angular_velocity_metrics,
+        **_get_velocity_statistics(linear_velocity, "linear_velocity"),
+        **_get_velocity_statistics(radial_velocity, "radial_velocity"),
+        **_get_velocity_statistics(angular_velocity, "angular_velocity"),
     }

src/graphomotor/utils/center_spiral.py

@@ -0,0 +1,18 @@
+"""Utility functions for centering a spiral."""
+
+from graphomotor.core import config, models
+
+
+def center_spiral(spiral: models.Spiral) -> models.Spiral:
+    """Center a spiral by translating it to the origin.
+
+    Args:
+        spiral: Spiral object containing spiral data.
+
+    Returns:
+        Spiral object with centered spiral data.
+    """
+    spiral.data["x"] -= config._SpiralConfig.SPIRAL_CENTER_X
+    spiral.data["y"] -= config._SpiralConfig.SPIRAL_CENTER_Y
+
+    return spiral

src/graphomotor/utils/reference_spiral.py …motor/utils/generate_reference_spiral.pysrc/graphomotor/utils/reference_spiral.py renamed to src/graphomotor/utils/generate_reference_spiral.py src/graphomotor/utils/reference_spiral.py renamed to src/graphomotor/utils/generate_reference_spiral.py

@@ -1,15 +1,9 @@
-"""Generate a reference spiral with equidistant points along its arc length."""
+"""Utility functions for generating an equidistant reference spiral."""
 
 import numpy as np
 from scipy import integrate, optimize
 
-_SPIRAL_CENTER_X = 50
-_SPIRAL_CENTER_Y = 50
-_SPIRAL_START_RADIUS = 0
-_SPIRAL_GROWTH_RATE = 1.075
-_SPIRAL_START_ANGLE = 0
-_SPIRAL_END_ANGLE = 8 * np.pi
-_SPIRAL_NUM_POINTS = 10000
+from graphomotor.core.config import _SpiralConfig
 
 
 def _arc_length_integrand(t: float) -> float:
@@ -21,8 +15,8 @@ def _arc_length_integrand(t: float) -> float:
     Returns:
         Differential arc length value.
     """
-    r_t = _SPIRAL_START_RADIUS + _SPIRAL_GROWTH_RATE * t
-    return np.sqrt(r_t**2 + _SPIRAL_GROWTH_RATE**2)
+    r_t = _SpiralConfig.SPIRAL_START_RADIUS + _SpiralConfig.SPIRAL_GROWTH_RATE * t
+    return np.sqrt(r_t**2 + _SpiralConfig.SPIRAL_GROWTH_RATE**2)
 
 
 def _calculate_arc_length(theta: float) -> float:
@@ -35,7 +29,7 @@ def _calculate_arc_length(theta: float) -> float:
         The arc length of the spiral from _SPIRAL_START_ANGLE to theta.
     """
     return integrate.quad(
-        lambda t: _arc_length_integrand(t), _SPIRAL_START_ANGLE, theta
+        lambda t: _arc_length_integrand(t), _SpiralConfig.SPIRAL_START_ANGLE, theta
     )[0]
 
 
@@ -50,7 +44,7 @@ def _find_theta_for_arc_length(target_arc_length: float) -> float:
     """
     solution = optimize.root_scalar(
         lambda theta: _calculate_arc_length(theta) - target_arc_length,
-        bracket=[_SPIRAL_START_ANGLE, _SPIRAL_END_ANGLE],
+        bracket=[_SpiralConfig.SPIRAL_START_ANGLE, _SpiralConfig.SPIRAL_END_ANGLE],
     )
     return solution.root
 
@@ -86,14 +80,19 @@ def generate_reference_spiral() -> np.ndarray:
     Returns:
         Array with shape (N, 2) containing Cartesian coordinates of the spiral points.
     """
-    total_arc_length = _calculate_arc_length(_SPIRAL_END_ANGLE)
+    total_arc_length = _calculate_arc_length(_SpiralConfig.SPIRAL_END_ANGLE)
 
-    arc_length_values = np.linspace(0, total_arc_length, _SPIRAL_NUM_POINTS)
+    arc_length_values = np.linspace(
+        0, total_arc_length, _SpiralConfig.SPIRAL_NUM_POINTS
+    )
 
     theta_values = np.array([_find_theta_for_arc_length(s) for s in arc_length_values])
 
-    r_values = _SPIRAL_START_RADIUS + _SPIRAL_GROWTH_RATE * theta_values
-    x_values = _SPIRAL_CENTER_X + r_values * np.cos(theta_values)
-    y_values = _SPIRAL_CENTER_Y + r_values * np.sin(theta_values)
+    r_values = (
+        _SpiralConfig.SPIRAL_START_RADIUS
+        + _SpiralConfig.SPIRAL_GROWTH_RATE * theta_values
+    )
+    x_values = _SpiralConfig.SPIRAL_CENTER_X + r_values * np.cos(theta_values)
+    y_values = _SpiralConfig.SPIRAL_CENTER_Y + r_values * np.sin(theta_values)
 
     return np.column_stack((x_values, y_values))

tests/conftest.py

@@ -8,7 +8,7 @@
 import pytest
 
 from graphomotor.core import models
-from graphomotor.utils import reference_spiral
+from graphomotor.utils import generate_reference_spiral
 
 
 @pytest.fixture
@@ -56,4 +56,4 @@ def valid_spiral(
 @pytest.fixture
 def ref_spiral() -> np.ndarray:
     """Create a reference spiral for testing."""
-    return reference_spiral.generate_reference_spiral()
+    return generate_reference_spiral.generate_reference_spiral()

tests/unit/test_drawing_error.py

@@ -20,4 +20,4 @@ def test_calculate_area_under_curve(valid_spiral: models.Spiral) -> None:
         valid_spiral, np.column_stack((x, y2))
     )["area_under_curve"]
 
-    assert np.isclose(calculated_area, expected_area, rtol=1e-3)
+    assert np.isclose(calculated_area, expected_area, atol=0, rtol=1e-3)

tests/unit/test_reference_spiral.py

@@ -2,33 +2,36 @@
 
 import numpy as np
 
-from graphomotor.utils import reference_spiral
+from graphomotor.core import config
+from graphomotor.utils import generate_reference_spiral
 
 
 def test_generate_reference_spiral() -> None:
     """Test the generation of a reference spiral."""
-    expected_mean_arc_length = reference_spiral._calculate_arc_length(
-        reference_spiral._SPIRAL_END_ANGLE
-    ) / (reference_spiral._SPIRAL_NUM_POINTS - 1)
+    expected_mean_arc_length = generate_reference_spiral._calculate_arc_length(
+        config._SpiralConfig.SPIRAL_END_ANGLE
+    ) / (config._SpiralConfig.SPIRAL_NUM_POINTS - 1)
 
-    spiral = reference_spiral.generate_reference_spiral()
+    spiral = generate_reference_spiral.generate_reference_spiral()
     arc_lengths = np.linalg.norm(spiral[1:] - spiral[:-1], axis=1)
     mean_arc_length = np.mean(arc_lengths)
 
     assert isinstance(spiral, np.ndarray)
-    assert spiral.shape == (reference_spiral._SPIRAL_NUM_POINTS, 2)
+    assert spiral.shape == (config._SpiralConfig.SPIRAL_NUM_POINTS, 2)
     assert np.array_equal(
         spiral[0],
-        [reference_spiral._SPIRAL_CENTER_X, reference_spiral._SPIRAL_CENTER_Y],
+        [config._SpiralConfig.SPIRAL_CENTER_X, config._SpiralConfig.SPIRAL_CENTER_Y],
     )
     assert np.allclose(
         spiral[-1],
         [
-            reference_spiral._SPIRAL_CENTER_X
-            + reference_spiral._SPIRAL_GROWTH_RATE * reference_spiral._SPIRAL_END_ANGLE,
-            reference_spiral._SPIRAL_CENTER_Y,
+            config._SpiralConfig.SPIRAL_CENTER_X
+            + config._SpiralConfig.SPIRAL_GROWTH_RATE
+            * config._SpiralConfig.SPIRAL_END_ANGLE,
+            config._SpiralConfig.SPIRAL_CENTER_Y,
         ],
-        atol=1e-8,
+        atol=0,
+        rtol=1e-8,
     )
-    assert np.allclose(arc_lengths, mean_arc_length, rtol=1e-3)
-    assert np.isclose(mean_arc_length, expected_mean_arc_length, rtol=1e-6)
+    assert np.allclose(arc_lengths, mean_arc_length, atol=0, rtol=1e-3)
+    assert np.isclose(mean_arc_length, expected_mean_arc_length, atol=0, rtol=1e-6)

tests/unit/test_velocity.py

@@ -3,7 +3,7 @@
 import numpy as np
 import pandas as pd
 
-from graphomotor.core import models
+from graphomotor.core import config, models
 from graphomotor.features import velocity
 
 
@@ -15,14 +15,38 @@ def test_calculate_velocity_metrics(valid_spiral: models.Spiral) -> None:
 
     t = np.linspace(0, time_total, num_points, endpoint=False)
     theta = np.linspace(0, theta_end, num_points, endpoint=False)
-    x = 50 + theta * np.cos(theta)
-    y = 50 + theta * np.sin(theta)
+    r = config._SpiralConfig.SPIRAL_GROWTH_RATE * theta
+    x = config._SpiralConfig.SPIRAL_CENTER_X + r * np.cos(theta)
+    y = config._SpiralConfig.SPIRAL_CENTER_Y + r * np.sin(theta)
 
     data = pd.DataFrame({"x": x, "y": y, "seconds": t})
     valid_spiral.data = data
 
-    expected_angular_velocity_sum = (theta_end / time_total) * (num_points - 1)
+    expected_angular_velocity_median = theta_end / time_total
+    expected_radial_velocity_median = (
+        config._SpiralConfig.SPIRAL_GROWTH_RATE * theta_end / time_total
+    )
+    expected_linear_velocity_median = np.median(
+        np.sqrt(np.gradient(x, t) ** 2 + np.gradient(y, t) ** 2)
+    )
 
     metrics = velocity.calculate_velocity_metrics(valid_spiral)
 
-    assert metrics["angular_velocity_sum"] == expected_angular_velocity_sum
+    assert np.isclose(
+        metrics["angular_velocity_median"],
+        expected_angular_velocity_median,
+        atol=0,
+        rtol=1e-14,
+    )
+    assert np.isclose(
+        metrics["radial_velocity_median"],
+        expected_radial_velocity_median,
+        atol=0,
+        rtol=1e-13,
+    )
+    assert np.isclose(
+        metrics["linear_velocity_median"],
+        expected_linear_velocity_median,
+        atol=0,
+        rtol=1e-4,
+    )