graphomotor.core

Core functionality for graphomotor data processing and analysis.

This module provides the essential infrastructure for the graphomotor toolkit:

Data Models and Validation

  • Spiral: Pydantic model for spiral drawing data validation with strict metadata requirements (7-digit participant IDs starting with '5', Dom/NonDom hand designation, spiral_trace/spiral_recall tasks numbered 1-5)
  • FeatureCategories: Registry of all 4 feature extractors (duration, velocity, hausdorff, AUC) with dynamic extractor mapping

Configuration and Logging

  • SpiralConfig: Immutable dataclass for Archimedean spiral parameters (center coordinates, growth rate, angles, point density) with custom parameter override support
  • Logger: Centralized logging with configurable verbosity levels (WARNING/INFO/DEBUG) and structured formatting

Pipeline Orchestration

  • run_pipeline(): Main entry point supporting both single-file and batch directory processing with progress tracking, error handling, and configurable feature extraction
  • Feature Extraction: Coordinates spiral centering, reference generation, and execution of all feature extractors
  • Export System: Automated CSV export with metadata preservation and timestamp-based naming

Command-Line Interface

  • extract: CLI command for feature extraction with extensive configuration options and help documentation
  • plot-features: CLI command for generating publication-ready visualizations from extracted feature datasets

The core module serves as the foundation for all graphomotor operations, ensuring data quality, processing consistency, and user-friendly interfaces.

 1"""Core functionality for graphomotor data processing and analysis.
 2
 3This module provides the essential infrastructure for the graphomotor toolkit:
 4
 5## Data Models and Validation
 6
 7- **`Spiral`**: Pydantic model for spiral drawing data validation with strict
 8  metadata requirements (7-digit participant IDs starting with '5', Dom/NonDom
 9  hand designation, spiral_trace/spiral_recall tasks numbered 1-5)
10- **`FeatureCategories`**: Registry of all 4 feature extractors (duration,
11  velocity, hausdorff, AUC) with dynamic extractor mapping
12
13## Configuration and Logging
14
15- **`SpiralConfig`**: Immutable dataclass for Archimedean spiral parameters
16  (center coordinates, growth rate, angles, point density) with custom
17  parameter override support
18- **Logger**: Centralized logging with configurable verbosity levels
19  (WARNING/INFO/DEBUG) and structured formatting
20
21## Pipeline Orchestration
22
23- **`run_pipeline()`**: Main entry point supporting both single-file and
24  batch directory processing with progress tracking, error handling, and
25  configurable feature extraction
26- **Feature Extraction**: Coordinates spiral centering, reference generation,
27  and execution of all feature extractors
28- **Export System**: Automated CSV export with metadata preservation and
29  timestamp-based naming
30
31## Command-Line Interface
32
33- **`extract`**: CLI command for feature extraction with extensive configuration
34  options and help documentation
35- **`plot-features`**: CLI command for generating publication-ready visualizations
36  from extracted feature datasets
37
38The core module serves as the foundation for all graphomotor operations, ensuring
39data quality, processing consistency, and user-friendly interfaces.
40"""