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/distance.py

@@ -31,7 +31,7 @@ def _segment_data(data: np.ndarray, start_prop: float, end_prop: float) -> np.nd
 
 def calculate_hausdorff_metrics(
     spiral: models.Spiral, reference_spiral: np.ndarray
-) -> dict:
+) -> dict[str, float]:
     """Calculate Hausdorff distance metrics for a spiral object.
 
     This function computes multiple features based on the Hausdorff distance between a

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[str, float]:
+    """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,23 @@
+"""Test cases for drawing_error.py functions."""
+
+import numpy as np
+import pandas as pd
+
+from graphomotor.core import models
+from graphomotor.features import drawing_error
+
+
+def test_calculate_area_under_curve(valid_spiral: models.Spiral) -> None:
+    """Test that the area under the curve is calculated correctly."""
+    x = np.linspace(-np.pi / 2, 3 * np.pi / 2, 100)
+    y1 = np.sin(x)
+    y2 = np.sin(x + np.pi)
+
+    expected_area = 8.0
+
+    valid_spiral.data = pd.DataFrame({"x": x, "y": y1})
+    calculated_area = drawing_error.calculate_area_under_curve(
+        valid_spiral, np.column_stack((x, y2))
+    )["area_under_curve"]
+
+    assert np.isclose(calculated_area, expected_area, rtol=1e-3)