graphomotor.features

 1"""Feature extraction modules for graphomotor data analysis.
 2
 3This module contains specialized extractors for computing clinically relevant metrics
 4across four categories: velocity (15 features), distance (8 features), drawing error
 5(1 feature), and time (1 feature). Each feature extractor follows a standardized
 6interface and returns a dictionary of computed metrics with descriptive keys.
 7
 8Available Features
 9------------------
10The graphomotor pipeline extracts 25 clinically validated features organized into
11four categories. These features quantify different aspects of drawing performance
12and motor control:
13
14**Distance-based Features (8 features):**
15
16These features use Hausdorff distance to measure spatial accuracy between drawn and
17reference spirals. The Hausdorff distance captures the maximum distance from any point
18in one set to the nearest point in another set.
19
20- **hausdorff_distance_maximum**: Maximum directed Hausdorff distance between drawn
21  and reference spiral points
22- **hausdorff_distance_sum**: Sum of directed Hausdorff distances
23- **hausdorff_distance_sum_per_second**: Sum of Hausdorff distances normalized by
24  total drawing duration
25- **hausdorff_distance_interquartile_range**: Interquartile range of directed
26  Hausdorff distances, measuring variability in spatial accuracy
27- **hausdorff_distance_start_segment_maximum_normalized**: Maximum Hausdorff distance
28  in beginning segment (0-25%) normalized by segment length
29- **hausdorff_distance_end_segment_maximum_normalized**: Maximum Hausdorff distance
30  in ending segment (75-100%) normalized by segment length
31- **hausdorff_distance_middle_segment_maximum**: Maximum Hausdorff distance in middle
32  segment (15-85%) without normalization
33- **hausdorff_distance_middle_segment_maximum_per_second**: Middle segment maximum
34  Hausdorff distance normalized by total drawing duration
35
36**Velocity-based Features (15 features):**
37
38These features analyze movement dynamics by computing velocity in three coordinate
39systems, each providing 5 statistical measures.
40
41*Linear velocity (5 features):*
42Euclidean velocity magnitude in Cartesian coordinates (pixels/second).
43
44- **linear_velocity_sum**: Sum of absolute linear velocity values
45- **linear_velocity_median**: Median of absolute linear velocity values
46- **linear_velocity_coefficient_of_variation**: Ratio of standard deviation to mean,
47  measuring velocity consistency
48- **linear_velocity_skewness**: Asymmetry of velocity distribution (positive =
49  right-skewed)
50- **linear_velocity_kurtosis**: Tailedness of velocity distribution (higher = more
51  extreme values)
52
53*Radial velocity (5 features):*
54Rate of change in distance from center (pixels/second).
55
56- **radial_velocity_sum**: Sum of absolute radial velocity values
57- **radial_velocity_median**: Median of absolute radial velocity values
58- **radial_velocity_coefficient_of_variation**: Consistency of radial movement speed
59- **radial_velocity_skewness**: Asymmetry of radial velocity distribution (positive =
60  right-skewed)
61- **radial_velocity_kurtosis**: Tailedness of radial velocity distribution
62  (higher = more extreme values)
63
64*Angular velocity (5 features):*
65Rate of angular rotation around center (radians/second).
66
67- **angular_velocity_sum**: Sum of absolute angular velocity values
68- **angular_velocity_median**: Median of absolute angular velocity values
69- **angular_velocity_coefficient_of_variation**: Consistency of rotational speed
70- **angular_velocity_skewness**: Asymmetry of angular velocity distribution (positive =
71  right-skewed)
72- **angular_velocity_kurtosis**: Tailedness of angular velocity distribution
73  (higher = more extreme values)
74
75**Time-based Features (1 feature):**
76
77- **duration**: Total time taken to complete the spiral drawing task (seconds)
78
79**Drawing Error Features (1 feature):**
80
81- **area_under_curve**: Total enclosed area between drawn and reference spiral paths,
82  computed using polygon intersection algorithms. Lower values indicate better
83  adherence to the template spiral.
84"""