graphomotor.features.spiral

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