graphomotor.utils

Utility functions and mathematical operations for graphomotor data processing.

This module provides essential computational and visualization support functions:

Reference Spiral Generation

  • Archimedean Spiral Mathematics: Implements r(θ) = a + b·θ with precise arc length calculations using numerical integration (scipy.integrate.quad)
  • Equidistant Point Distribution: Uses root-finding algorithms to place points at equal arc length intervals along the spiral curve
  • LRU Caching: Memoizes expensive spiral computations for performance optimization across repeated operations
  • Configurable Parameters: Supports custom center coordinates, growth rates, angle ranges, and point density through SpiralConfig

Geometric Transformations

  • Spiral Centering: Type-overloaded function supporting both Spiral objects and numpy arrays with automatic coordinate translation to origin
  • Coordinate System Normalization: Translates spiral data to standardized reference frame for consistent feature extraction

Plotting Infrastructure

  • Data Validation Pipeline: Comprehensive DataFrame validation using Spiral model constraints (7-digit participant IDs, Dom/NonDom hands, valid tasks)
  • Task Metadata Enhancement: Adds task ordering and categorization (trace/recall) for structured visualization
  • Dynamic Subplot Generation: Adaptive grid layouts based on feature count with responsive sizing algorithms
  • Feature Name Formatting: Intelligent text wrapping for readable plot labels
  • High-Quality Export: PNG output with 300 DPI resolution and timestamp-based naming

These utilities ensure mathematical precision and computational efficiency throughout the graphomotor analysis pipeline.

 1"""Utility functions and mathematical operations for graphomotor data processing.
 2
 3This module provides essential computational and visualization support functions:
 4
 5## Reference Spiral Generation
 6
 7- **Archimedean Spiral Mathematics**: Implements r(θ) = a + b·θ with precise
 8  arc length calculations using numerical integration (scipy.integrate.quad)
 9- **Equidistant Point Distribution**: Uses root-finding algorithms to place
10  points at equal arc length intervals along the spiral curve
11- **LRU Caching**: Memoizes expensive spiral computations for performance
12  optimization across repeated operations
13- **Configurable Parameters**: Supports custom center coordinates, growth rates,
14  angle ranges, and point density through SpiralConfig
15
16## Geometric Transformations
17
18- **Spiral Centering**: Type-overloaded function supporting both Spiral objects
19  and numpy arrays with automatic coordinate translation to origin
20- **Coordinate System Normalization**: Translates spiral data to standardized
21  reference frame for consistent feature extraction
22
23## Plotting Infrastructure
24
25- **Data Validation Pipeline**: Comprehensive DataFrame validation using Spiral
26  model constraints (7-digit participant IDs, Dom/NonDom hands, valid tasks)
27- **Task Metadata Enhancement**: Adds task ordering and categorization
28  (trace/recall) for structured visualization
29- **Dynamic Subplot Generation**: Adaptive grid layouts based on feature count
30  with responsive sizing algorithms
31- **Feature Name Formatting**: Intelligent text wrapping for readable plot labels
32- **High-Quality Export**: PNG output with 300 DPI resolution
33  and timestamp-based naming
34
35These utilities ensure mathematical precision and computational efficiency
36throughout the graphomotor analysis pipeline.
37"""