feature/issue-19/implement-drawing-error-features

pyproject.toml

@@ -11,7 +11,8 @@ requires-python = ">=3.12"
 dependencies = [
   "pandas>=2.2.3",
   "pydantic>=2.11.1",
-  "scipy>=1.15.2"
+  "scipy>=1.15.2",
+  "shapely>=2.1.0"
 ]
 
 [dependency-groups]

src/graphomotor/features/drawing_error.py

@@ -0,0 +1,36 @@
+"""Feature extraction module for drawing error-based metrics in spiral drawing data."""
+
+import numpy as np
+from shapely import geometry, ops
+
+from graphomotor.core import models
+
+
+def calculate_area_under_curve(
+    drawn_spiral: models.Spiral, reference_spiral: np.ndarray
+) -> dict:
+    """Calculate the area between drawn and reference spirals.
+
+    This function measures the deviation between drawn and reference spirals by
+    computing the enclosed area between them using the shapely library. Lower values
+    indicate better adherence to the template. The algorithm works by creating polygons
+    that connect spiral endpoints, finding intersections between lines, and calculating
+    the total area of the resulting polygons.
+
+    Args:
+        drawn_spiral: The spiral drawn by the subject.
+        reference_spiral: The reference spiral.
+
+    Returns:
+        Dictionary containing the area under curve metric
+    """
+    spiral = drawn_spiral.data[["x", "y"]].values
+    line_drawn = geometry.LineString(spiral)
+    line_reference = geometry.LineString(reference_spiral)
+    first_segment = geometry.LineString([spiral[0], reference_spiral[0]])
+    last_segment = geometry.LineString([spiral[-1], reference_spiral[-1]])
+    merged_line = ops.unary_union(
+        [line_drawn, line_reference, first_segment, last_segment]
+    )
+    polygons = list(ops.polygonize(merged_line))
+    return {"area_under_curve": sum(p.area for p in polygons)}

tests/unit/test_drawing_error.py

@@ -0,0 +1,34 @@
+"""Test cases for drawing_error.py functions."""
+
+import numpy as np
+import pandas as pd
+import pytest
+from scipy import integrate
+
+from graphomotor.core import models
+from graphomotor.features import drawing_error
+
+
+def test_calculate_area_under_curve(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that the area under the curve is calculated correctly."""
+    x = np.linspace(-np.pi / 2, 6 * np.pi / 4, 100)
+    y1 = np.sin(x)
+    y2 = np.sin(x + np.pi)
+
+    expected_area, _ = integrate.quad(
+        lambda x: np.abs(np.sin(x) - np.sin(x + np.pi)), -np.pi / 2, 6 * np.pi / 4
+    )
+
+    class MockSpiral:
+        def __init__(self, data: pd.DataFrame, metadata: dict) -> None:
+            self.data = data
+            self.metadata = metadata
+
+    monkeypatch.setattr(models, "Spiral", MockSpiral)
+
+    calculated_area = drawing_error.calculate_area_under_curve(
+        models.Spiral(data=pd.DataFrame({"x": x, "y": y1}), metadata={}),
+        np.array([x, y2]).T,
+    )["area_under_curve"]
+
+    assert np.isclose(calculated_area, expected_area, rtol=1e-3)