kinemotion 0.76.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/squat_jump/metrics_validator.py

@@ -1,438 +0,0 @@
-"""SJ metrics validation using physiological bounds.
-
-Comprehensive validation of Squat Jump metrics against
-biomechanical bounds and consistency tests.
-
-Provides severity levels (ERROR, WARNING, INFO) for different categories
-of metric issues.
-"""
-
-from dataclasses import dataclass
-
-from kinemotion.core.types import MetricsDict
-from kinemotion.core.validation import (
-    AthleteProfile,
-    MetricsValidator,
-    ValidationResult,
-)
-from kinemotion.squat_jump.validation_bounds import (
-    MetricConsistency,
-    SJBounds,
-    estimate_athlete_profile,
-)
-
-
-@dataclass
-class SJValidationResult(ValidationResult):
-    """SJ-specific validation result."""
-
-    peak_power_consistency: float | None = None
-    force_height_consistency: float | None = None
-
-    def to_dict(self) -> dict:
-        """Convert validation result to JSON-serializable dictionary.
-
-        Returns:
-            Dictionary with status, issues, and consistency metrics.
-        """
-        return {
-            "status": self.status,
-            "issues": [
-                {
-                    "severity": issue.severity.value,
-                    "metric": issue.metric,
-                    "message": issue.message,
-                    "value": issue.value,
-                    "bounds": issue.bounds,
-                }
-                for issue in self.issues
-            ],
-            "athlete_profile": (self.athlete_profile.value if self.athlete_profile else None),
-            "peak_power_consistency_percent": self.peak_power_consistency,
-            "force_height_consistency_percent": self.force_height_consistency,
-        }
-
-
-class SJMetricsValidator(MetricsValidator):
-    """Comprehensive SJ metrics validator."""
-
-    @staticmethod
-    def _get_metric_value(
-        data: dict, key_with_suffix: str, key_without_suffix: str
-    ) -> float | None:
-        """Get metric value, supporting both suffixed and legacy key formats.
-
-        Args:
-            data: Dictionary containing metrics
-            key_with_suffix: Key with unit suffix (e.g., "flight_time_ms")
-            key_without_suffix: Legacy key without suffix (e.g., "flight_time")
-
-        Returns:
-            Metric value or None if not found
-        """
-        return data.get(key_with_suffix) or data.get(key_without_suffix)
-
-    @staticmethod
-    def _convert_raw_duration_to_seconds(value_raw: float) -> float:
-        """Convert raw duration value to seconds.
-
-        Handles legacy values that may be in seconds (<10) vs milliseconds (>10).
-        This heuristic works because no SJ duration metric is between 10ms and 10s.
-
-        Args:
-            value_raw: Raw duration value (may be seconds or milliseconds)
-
-        Returns:
-            Duration in seconds
-        """
-        if value_raw < 10:  # Likely in seconds
-            return value_raw
-        return value_raw / 1000.0
-
-    def validate(self, metrics: MetricsDict) -> SJValidationResult:
-        """Validate SJ metrics comprehensively.
-
-        Args:
-            metrics: Dictionary with SJ metric values
-
-        Returns:
-            SJValidationResult with all issues and status
-        """
-        result = SJValidationResult()
-
-        # Estimate athlete profile if not provided
-        if self.assumed_profile:
-            result.athlete_profile = self.assumed_profile
-        else:
-            result.athlete_profile = estimate_athlete_profile(metrics)
-
-        profile = result.athlete_profile
-
-        # Extract metric values (handle nested "data" structure)
-        data = metrics.get("data", metrics)  # Support both structures
-
-        # PRIMARY BOUNDS CHECKS
-        self._check_flight_time(data, result, profile)
-        self._check_jump_height(data, result, profile)
-        self._check_squat_hold_duration(data, result)
-        self._check_concentric_duration(data, result)
-        self._check_peak_concentric_velocity(data, result, profile)
-        self._check_power_metrics(data, result)
-        self._check_force_metrics(data, result)
-
-        # CROSS-VALIDATION CHECKS
-        self._check_flight_time_height_consistency(data, result)
-        self._check_power_velocity_consistency(data, result)
-
-        # CONSISTENCY CHECKS
-        self._check_squat_concentric_ratio(data, result)
-
-        # Finalize status
-        result.finalize_status()
-
-        return result
-
-    def _check_flight_time(
-        self, metrics: MetricsDict, result: SJValidationResult, profile: AthleteProfile
-    ) -> None:
-        """Validate flight time."""
-        flight_time_raw = self._get_metric_value(metrics, "flight_time_ms", "flight_time")
-        if flight_time_raw is None:
-            return
-
-        flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
-        bounds = SJBounds.FLIGHT_TIME
-        error_label = (
-            "below frame rate resolution limit"
-            if flight_time < bounds.absolute_min
-            else "exceeds elite human capability"
-        )
-
-        self._validate_metric_with_bounds(
-            "flight_time",
-            flight_time,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_label,
-            format_str="{value:.3f}s",
-        )
-
-    def _check_jump_height(
-        self, metrics: MetricsDict, result: SJValidationResult, profile: AthleteProfile
-    ) -> None:
-        """Validate jump height."""
-        jump_height = self._get_metric_value(metrics, "jump_height_m", "jump_height")
-        if jump_height is None:
-            return
-
-        bounds = SJBounds.JUMP_HEIGHT
-        error_label = (
-            "essentially no jump (noise)"
-            if jump_height < bounds.absolute_min
-            else "exceeds human capability"
-        )
-
-        self._validate_metric_with_bounds(
-            "jump_height",
-            jump_height,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_label,
-            format_str="{value:.3f}m",
-        )
-
-    def _check_squat_hold_duration(self, metrics: MetricsDict, result: SJValidationResult) -> None:
-        """Validate squat hold duration."""
-        duration_raw = self._get_metric_value(
-            metrics, "squat_hold_duration_ms", "squat_hold_duration"
-        )
-        if duration_raw is None:
-            return
-
-        duration = self._convert_raw_duration_to_seconds(duration_raw)
-        bounds = SJBounds.SQUAT_HOLD_DURATION
-
-        if not bounds.is_physically_possible(duration):
-            result.add_error(
-                "squat_hold_duration",
-                f"Squat hold duration {duration:.3f}s outside physical limits",
-                value=duration,
-                bounds=(bounds.absolute_min, bounds.absolute_max),
-            )
-        else:
-            result.add_info(
-                "squat_hold_duration",
-                f"Squat hold duration {duration:.3f}s",
-                value=duration,
-            )
-
-    def _check_concentric_duration(self, metrics: MetricsDict, result: SJValidationResult) -> None:
-        """Validate concentric duration."""
-        duration_raw = self._get_metric_value(
-            metrics, "concentric_duration_ms", "concentric_duration"
-        )
-        if duration_raw is None:
-            return
-
-        duration = self._convert_raw_duration_to_seconds(duration_raw)
-        bounds = SJBounds.CONCENTRIC_DURATION
-
-        if not bounds.is_physically_possible(duration):
-            if duration < bounds.absolute_min:
-                result.add_error(
-                    "concentric_duration",
-                    f"Concentric duration {duration:.3f}s likely detection error",
-                    value=duration,
-                    bounds=(bounds.absolute_min, bounds.absolute_max),
-                )
-            else:
-                result.add_error(
-                    "concentric_duration",
-                    f"Concentric duration {duration:.3f}s includes pre-takeoff phase",
-                    value=duration,
-                    bounds=(bounds.absolute_min, bounds.absolute_max),
-                )
-        else:
-            result.add_info(
-                "concentric_duration",
-                f"Concentric duration {duration:.3f}s",
-                value=duration,
-            )
-
-    def _check_peak_concentric_velocity(
-        self, metrics: MetricsDict, result: SJValidationResult, profile: AthleteProfile
-    ) -> None:
-        """Validate peak concentric velocity."""
-        velocity = self._get_metric_value(
-            metrics, "peak_concentric_velocity_m_s", "peak_concentric_velocity"
-        )
-        if velocity is None:
-            return
-
-        bounds = SJBounds.PEAK_CONCENTRIC_VELOCITY
-        error_suffix = "insufficient to leave ground" if velocity < bounds.absolute_min else ""
-
-        self._validate_metric_with_bounds(
-            "peak_concentric_velocity",
-            velocity,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_suffix,
-            format_str="{value:.3f} m/s",
-        )
-
-    def _check_power_metrics(self, metrics: MetricsDict, result: SJValidationResult) -> None:
-        """Validate power metrics (peak and mean)."""
-        power_checks = [
-            ("peak_power", "peak_power_w", SJBounds.PEAK_POWER, ""),
-            ("mean_power", "mean_power_w", SJBounds.MEAN_POWER, ""),
-        ]
-
-        for metric_name, key_name, bounds, _error_suffix in power_checks:
-            power = self._get_metric_value(metrics, key_name, metric_name)
-            if power is None:
-                continue
-
-            # Skip validation if mass wasn't provided (power calculations require mass)
-            if power == 0 and metrics.get("mass_kg") is None:
-                result.add_info(
-                    metric_name,
-                    f"{metric_name.replace('_', ' ').title()} not calculated (mass not provided)",
-                    value=power,
-                )
-                continue
-
-            if not bounds.is_physically_possible(power):
-                result.add_error(
-                    metric_name,
-                    f"Peak {metric_name.replace('_', ' ')} {power:.0f} W outside physical limits",
-                    value=power,
-                    bounds=(bounds.absolute_min, bounds.absolute_max),
-                )
-            else:
-                result.add_info(
-                    metric_name,
-                    f"{metric_name.replace('_', ' ').title()} {power:.0f} W",
-                    value=power,
-                )
-
-    def _check_force_metrics(self, metrics: MetricsDict, result: SJValidationResult) -> None:
-        """Validate force metrics."""
-        peak_force = self._get_metric_value(metrics, "peak_force_n", "peak_force")
-        if peak_force is None:
-            return
-
-        # Skip validation if mass wasn't provided
-        if peak_force == 0 and metrics.get("mass_kg") is None:
-            result.add_info(
-                "peak_force",
-                "Peak force not calculated (mass not provided)",
-                value=peak_force,
-            )
-            return
-
-        bounds = SJBounds.PEAK_FORCE
-
-        if not bounds.is_physically_possible(peak_force):
-            result.add_error(
-                "peak_force",
-                f"Peak force {peak_force:.0f} N outside physical limits",
-                value=peak_force,
-                bounds=(bounds.absolute_min, bounds.absolute_max),
-            )
-        else:
-            result.add_info(
-                "peak_force",
-                f"Peak force {peak_force:.0f} N",
-                value=peak_force,
-            )
-
-    def _check_flight_time_height_consistency(
-        self, metrics: MetricsDict, result: SJValidationResult
-    ) -> None:
-        """Verify jump height is consistent with flight time."""
-        flight_time_ms = metrics.get("flight_time_ms")
-        jump_height = metrics.get("jump_height_m")
-
-        if flight_time_ms is None or jump_height is None:
-            return
-
-        # Convert ms to seconds
-        flight_time = flight_time_ms / 1000.0
-
-        # Calculate expected height using kinematic formula: h = g*t²/8
-        g = 9.81
-        expected_height = (g * flight_time**2) / 8
-        error_pct = abs(jump_height - expected_height) / expected_height
-
-        result.force_height_consistency = error_pct
-
-        if error_pct > MetricConsistency.HEIGHT_FLIGHT_TIME_TOLERANCE:
-            result.add_error(
-                "height_flight_time_consistency",
-                f"Jump height {jump_height:.3f}m inconsistent with flight "
-                f"time {flight_time:.3f}s (expected {expected_height:.3f}m, "
-                f"error {error_pct * 100:.1f}%)",
-                value=error_pct,
-                bounds=(0, MetricConsistency.HEIGHT_FLIGHT_TIME_TOLERANCE),
-            )
-        else:
-            result.add_info(
-                "height_flight_time_consistency",
-                f"Jump height and flight time consistent (error {error_pct * 100:.1f}%)",
-                value=error_pct,
-            )
-
-    def _check_power_velocity_consistency(
-        self, metrics: MetricsDict, result: SJValidationResult
-    ) -> None:
-        """Verify power is consistent with velocity and mass."""
-        velocity = metrics.get("peak_concentric_velocity_m_s")
-        peak_power = metrics.get("peak_power_w")
-        mass_kg = metrics.get("mass_kg")
-
-        if velocity is None or peak_power is None or mass_kg is None:
-            return
-
-        # Calculate expected power: P = F × v = (m × a) × v
-        # For simplicity, assume peak acceleration occurs at peak velocity
-        # TODO: This needs biomechanical validation by specialist
-        g = 9.81
-        # Estimate force during concentric phase (simplified)
-        expected_force = mass_kg * g * 2  # Assume 2x bodyweight force
-        expected_power = expected_force * velocity
-        error_pct = abs(peak_power - expected_power) / expected_power
-
-        result.peak_power_consistency = error_pct
-
-        if error_pct > MetricConsistency.POWER_VELOCITY_TOLERANCE:
-            result.add_warning(
-                "power_velocity_consistency",
-                f"Peak power {peak_power:.0f} W inconsistent with velocity "
-                f"{velocity:.2f} m/s and mass {mass_kg:.1f} kg "
-                f"(expected ~{expected_power:.0f} W, error {error_pct * 100:.1f}%)",
-                value=error_pct,
-                bounds=(0, MetricConsistency.POWER_VELOCITY_TOLERANCE),
-            )
-        else:
-            result.add_info(
-                "power_velocity_consistency",
-                f"Power and velocity consistent (error {error_pct * 100:.1f}%)",
-                value=error_pct,
-            )
-
-    def _check_squat_concentric_ratio(
-        self, metrics: MetricsDict, result: SJValidationResult
-    ) -> None:
-        """Check squat hold duration to concentric duration ratio."""
-        squat_ms = metrics.get("squat_hold_duration_ms")
-        concentric_ms = metrics.get("concentric_duration_ms")
-
-        if squat_ms is None or concentric_ms is None or concentric_ms < 50:
-            return
-
-        # Convert to seconds for ratio calculation
-        squat = squat_ms / 1000.0
-        concentric = concentric_ms / 1000.0
-        ratio = squat / concentric
-
-        if ratio > MetricConsistency.SQUAT_CONCENTRIC_RATIO_MAX:
-            result.add_warning(
-                "squat_concentric_ratio",
-                f"Squat hold {ratio:.2f}x concentric duration: "
-                f"Unusually long static phase, verify squat detection",
-                value=ratio,
-                bounds=(
-                    MetricConsistency.SQUAT_CONCENTRIC_RATIO_MIN,
-                    MetricConsistency.SQUAT_CONCENTRIC_RATIO_MAX,
-                ),
-            )
-        else:
-            result.add_info(
-                "squat_concentric_ratio",
-                f"Squat-to-concentric ratio {ratio:.2f} within expected range",
-                value=ratio,
-            )

kinemotion/squat_jump/validation_bounds.py

@@ -1,221 +0,0 @@
-"""SJ metrics physiological bounds for validation testing.
-
-This module defines realistic physiological bounds for Squat Jump (SJ)
-metrics based on biomechanical literature and real-world athlete performance.
-
-These bounds are used to:
-1. Prevent false positives from measurement noise
-2. Catch real errors in video processing and phase detection
-3. Provide athlete-profile-appropriate validation
-4. Enable cross-validation of metric consistency
-
-Note: SJ metrics differ from CMJ as there is no eccentric phase.
-Focus is on static squat hold duration and explosive concentric phase.
-"""
-
-from kinemotion.core.types import MetricsDict
-from kinemotion.core.validation import AthleteProfile, MetricBounds
-
-
-class SJBounds:
-    """Collection of physiological bounds for all SJ metrics."""
-
-    # FLIGHT TIME (seconds)
-    FLIGHT_TIME = MetricBounds(
-        absolute_min=0.08,  # Frame rate resolution limit
-        practical_min=0.15,  # Minimum effort jump
-        recreational_min=0.20,  # Untrained ~5-10cm
-        recreational_max=0.50,  # Recreational ~20-35cm
-        elite_min=0.55,  # Trained ~50cm
-        elite_max=1.00,  # Elite >80cm
-        absolute_max=1.20,
-        unit="s",
-    )
-
-    # JUMP HEIGHT (meters) - SJ typically achieves less than CMJ
-    JUMP_HEIGHT = MetricBounds(
-        absolute_min=0.02,
-        practical_min=0.05,
-        recreational_min=0.10,  # Untrained with effort
-        recreational_max=0.45,  # Good recreational
-        elite_min=0.50,
-        elite_max=0.85,
-        absolute_max=1.20,
-        unit="m",
-    )
-
-    # SQUAT HOLD DURATION (seconds) - Key SJ-specific metric
-    SQUAT_HOLD_DURATION = MetricBounds(
-        absolute_min=0.0,  # Can be very short
-        practical_min=0.0,
-        recreational_min=0.0,  # May not be detectable
-        recreational_max=2.0,  # Very long static holds
-        elite_min=0.0,
-        elite_max=3.0,  # Elite athletes sometimes use long pauses
-        absolute_max=5.0,  # Maximum reasonable squat hold
-        unit="s",
-    )
-
-    # CONCENTRIC DURATION (seconds) - Similar to CMJ concentric phase
-    CONCENTRIC_DURATION = MetricBounds(
-        absolute_min=0.08,
-        practical_min=0.15,  # Extreme plyometric
-        recreational_min=0.30,  # Moderate propulsion
-        recreational_max=0.70,  # Slow push-off
-        elite_min=0.20,
-        elite_max=0.45,
-        absolute_max=1.50,
-        unit="s",
-    )
-
-    # PEAK CONCENTRIC VELOCITY (m/s, upward) - Key SJ metric
-    PEAK_CONCENTRIC_VELOCITY = MetricBounds(
-        absolute_min=0.30,
-        practical_min=0.50,
-        recreational_min=1.60,
-        recreational_max=2.60,
-        elite_min=2.80,
-        elite_max=4.00,
-        absolute_max=5.00,
-        unit="m/s",
-    )
-
-    # PEAK POWER (Watts) - Requires mass calculation
-    PEAK_POWER = MetricBounds(
-        absolute_min=1000,  # Minimum for adult
-        practical_min=1500,
-        recreational_min=3000,
-        recreational_max=8000,
-        elite_min=9000,
-        elite_max=15000,
-        absolute_max=20000,
-        unit="W",
-    )
-
-    # MEAN POWER (Watts) - During concentric phase
-    MEAN_POWER = MetricBounds(
-        absolute_min=500,  # Minimum for adult
-        practical_min=800,
-        recreational_min=1500,
-        recreational_max=5000,
-        elite_min=6000,
-        elite_max=10000,
-        absolute_max=15000,
-        unit="W",
-    )
-
-    # PEAK FORCE (Newtons) - During concentric phase
-    PEAK_FORCE = MetricBounds(
-        absolute_min=1000,  # Minimum for adult
-        practical_min=1500,
-        recreational_min=2000,
-        recreational_max=4000,
-        elite_min=4500,
-        elite_max=6000,
-        absolute_max=8000,
-        unit="N",
-    )
-
-
-class MetricConsistency:
-    """Cross-validation tolerance for metric consistency checks."""
-
-    # Jump height from flight time: h = g*t²/8
-    # Allow 10% deviation for measurement noise
-    HEIGHT_FLIGHT_TIME_TOLERANCE = 0.10
-
-    # Power from velocity and mass: P = F × v
-    # Allow 25% deviation (power calculations are complex)
-    POWER_VELOCITY_TOLERANCE = 0.25
-
-    # Squat hold to concentric duration ratio
-    # Typically 0-2.0, flag if outside 0-3.0
-    SQUAT_CONCENTRIC_RATIO_MIN = 0.0
-    SQUAT_CONCENTRIC_RATIO_MAX = 3.0
-
-
-# Athlete profile examples with expected metric ranges
-ATHLETE_PROFILES = {
-    "elderly_deconditioned": {
-        "label": "Elderly/Deconditioned (70+, sedentary)",
-        "profile": AthleteProfile.ELDERLY,
-        "expected": {
-            "jump_height_m": (0.05, 0.15),
-            "flight_time_s": (0.10, 0.18),
-            "squat_hold_duration_s": (0.0, 1.5),
-            "concentric_duration_s": (0.40, 0.90),
-            "peak_concentric_velocity_ms": (0.8, 1.4),
-            "peak_power_w": (1500, 3000),
-            "mean_power_w": (800, 2000),
-            "peak_force_n": (1500, 3000),
-        },
-    },
-    "recreational": {
-        "label": "Recreational Athlete (fitness participant, 30-45 yrs)",
-        "profile": AthleteProfile.RECREATIONAL,
-        "expected": {
-            "jump_height_m": (0.20, 0.45),
-            "flight_time_s": (0.25, 0.50),
-            "squat_hold_duration_s": (0.0, 1.0),
-            "concentric_duration_s": (0.35, 0.65),
-            "peak_concentric_velocity_ms": (1.8, 2.5),
-            "peak_power_w": (4000, 7000),
-            "mean_power_w": (2000, 4500),
-            "peak_force_n": (2500, 3500),
-        },
-    },
-    "elite_male": {
-        "label": "Elite Male Athlete (college/pro volleyball/basketball)",
-        "profile": AthleteProfile.ELITE,
-        "expected": {
-            "jump_height_m": (0.60, 0.85),
-            "flight_time_s": (0.70, 0.80),
-            "squat_hold_duration_s": (0.0, 1.5),
-            "concentric_duration_s": (0.25, 0.40),
-            "peak_concentric_velocity_ms": (3.2, 3.8),
-            "peak_power_w": (10000, 14000),
-            "mean_power_w": (6000, 9000),
-            "peak_force_n": (4500, 5500),
-        },
-    },
-}
-
-
-def estimate_athlete_profile(
-    metrics_dict: MetricsDict, _gender: str | None = None
-) -> AthleteProfile:
-    """Estimate athlete profile from SJ metrics.
-
-    Uses jump height as primary classifier (similar to CMJ):
-    - <0.15m: Elderly
-    - 0.15-0.20m: Untrained
-    - 0.20-0.45m: Recreational
-    - 0.45-0.50m: Trained
-    - >0.50m: Elite
-
-    NOTE: Squat Jump typically achieves lower heights than CMJ due to
-    the lack of pre-stretch (no countermovement). Adjust expectations
-    accordingly when analyzing results.
-
-    Args:
-        metrics_dict: Dictionary with SJ metric values
-        gender: Optional gender for context ("M"/"F"). Currently informational only.
-
-    Returns:
-        Estimated AthleteProfile
-    """
-    # Support both nested "data" structure and flat structure
-    # Extract with unit suffix as used in serialization, or without suffix (legacy)
-    data = metrics_dict.get("data", metrics_dict)
-    jump_height = data.get("jump_height_m") or data.get("jump_height", 0)
-
-    if jump_height < 0.15:
-        return AthleteProfile.ELDERLY
-    elif jump_height < 0.20:
-        return AthleteProfile.UNTRAINED
-    elif jump_height < 0.45:
-        return AthleteProfile.RECREATIONAL
-    elif jump_height < 0.50:
-        return AthleteProfile.TRAINED
-    else:
-        return AthleteProfile.ELITE