56 task write trails drawing feature functions get total errors (#91)

* wrote function

* write unit test

* valid unit test

* change documentation and edit output from detect_pen_lifts to be the same as get_total_errors

* rewrite unit test with actual sample data, fix detect_pen_lift unit tests for new output format

Author: cgmaiorano

src/graphomotor/features/trails/drawing_metrics.py

@@ -3,7 +3,7 @@
 from graphomotor.core import models
 
 
-def detect_pen_lifts(drawing: models.Drawing) -> int:
+def detect_pen_lifts(drawing: models.Drawing) -> dict[str, int]:
     """Detect pen lifts during a spiral drawing task.
 
     Args:
@@ -12,4 +12,20 @@ def detect_pen_lifts(drawing: models.Drawing) -> int:
     Returns:
         Integer count of pen lifts detected.
     """
-    return len(drawing.data["line_number"].unique()) - 1
+    return {"pen_lifts": len(drawing.data["line_number"].unique()) - 1}
+
+
+def get_total_errors(drawing: models.Drawing) -> dict[str, float]:
+    """Extract the total number of errors of a trails drawing task.
+
+    Args:
+        drawing: Drawing object containing drawing data.
+
+    Returns:
+        Dictionary containing the total number of errors of the task.
+    """
+    if "total_number_of_errors" not in drawing.data.columns:
+        raise ValueError(
+            "Drawing data does not contain 'total_number_of_errors' column."
+        )
+    return {"total_errors": drawing.data["total_number_of_errors"].iloc[0]}

tests/unit/test_trails_drawing_metrics.py

@@ -1,20 +1,47 @@
 """Test cases for drawing_metrics.py functions."""
 
 import pandas as pd
+import pytest
 
 from graphomotor.core import models
 from graphomotor.features.trails import drawing_metrics
+from graphomotor.io import reader
 
 
 def test_no_pen_lifts() -> None:
     """Test case with no pen lifts."""
     df = pd.DataFrame({"line_number": [1, 1, 1, 1]})
     drawing = models.Drawing(data=df, task_name="trails", metadata={"id": "5555555"})
-    assert drawing_metrics.detect_pen_lifts(drawing) == 0
+    result = drawing_metrics.detect_pen_lifts(drawing)
+    assert result == {"pen_lifts": 0}
 
 
 def test_valid_pen_lifts() -> None:
     """Test case with valid pen lifts."""
     df = pd.DataFrame({"line_number": [1, 2, 3, 4]})
     drawing = models.Drawing(data=df, task_name="trails", metadata={"id": "5555555"})
-    assert drawing_metrics.detect_pen_lifts(drawing) == 3
+    result = drawing_metrics.detect_pen_lifts(drawing)
+    assert result == {"pen_lifts": 3}
+
+
+def test_get_total_errors() -> None:
+    """Test ValueError when total_number_of_errors column doesn't exist."""
+    invalid_df = pd.DataFrame({"some_other_column": [0, 1, 2]})
+    drawing = models.Drawing(
+        data=invalid_df, task_name="trails", metadata={"id": "5555555"}
+    )
+
+    with pytest.raises(
+        ValueError,
+        match="Drawing data does not contain 'total_number_of_errors' column.",
+    ):
+        drawing_metrics.get_total_errors(drawing)
+
+
+def test_valid_total_errors() -> None:
+    """Test case with valid total_number_of_errors column."""
+    filepath = "tests/sample_data/[5000000]648b6b868819c1120b4f6ce3-trail4.csv"
+    drawing = reader.load_drawing_data(filepath)
+
+    result = drawing_metrics.get_total_errors(drawing)
+    assert result == {"total_errors": 1.0}