bowling-analysis-system

Bowling Metrics Processing Utilities

A comprehensive set of utilities for processing and validating bowling metrics time series data. This library provides functionality for normalizing, extracting, analyzing, and visualizing time series data with a focus on bowling metrics.

Features

• Time Series Data Extraction: Extract specific metrics or segments between events
• Left/Right Normalization: Standardize left/right pair metrics with average calculations
• Metrics Validation: Validate metrics against required structure and events
• Statistical Analysis: Calculate key statistics for time series data
• Visualization Configuration: Generate configuration for charting time series data

Installation

npm install

Quick Start

import { timeSeriesUtils, metricsValidator } from './src/utils';

// Load your metrics data
const metricsData = JSON.parse(fs.readFileSync('path/to/metrics.json', 'utf8'));

// Validate metrics
const validationResult = metricsValidator.validateMetrics(metricsData);
console.log(`Metrics validation: ${validationResult.isValid ? 'PASSED' : 'FAILED'}`);

// Extract time series data
const armAngles = timeSeriesUtils.extractByPath(metricsData, 'timeSeries.angles.armAngles');

// Calculate statistics
const stats = timeSeriesUtils.calculateStatistics(armAngles, true);
console.log('Left arm stats:', stats.left);
console.log('Right arm stats:', stats.right);
console.log('Average stats:', stats.average);

// Extract data between events
const dataSegment = timeSeriesUtils.extractBetweenEvents(
    metricsData,
    'timeSeries.angles.armAngles',
    'backFootLanding',
    'releasePoint'
);

// Create visualization config
const chartConfig = timeSeriesUtils.createVisualizationConfig(
    armAngles,
    {
        title: 'Arm Angles During Bowling',
        xLabel: 'Frame',
        yLabel: 'Angle (degrees)',
        hasLeftRight: true
    },
    metricsData.events
);

Validation Rules

The metricsValidator module enforces the following validation rules:

• Required Events: frontFootLanding, backFootLanding, releasePoint
• Required Categories: angles, position, velocity
• Structural Validation: Consistent array lengths across time series
• Left/Right Validation: Proper format with left, right, and average properties

Time Series Utilities

The timeSeriesUtils module provides the following key functions:

• normalizeTimeSeries(): Convert time series data to standard left/right/average format
• extractByPath(): Extract data from a nested object using dot notation
• extractBetweenEvents(): Extract time series data between two events
• calculateStatistics(): Calculate statistics for time series data
• createVisualizationConfig(): Create chart configuration for time series data
• validateTimeSeriesStructure(): Validate time series structure
• discoverTimeSeriesMetrics(): Find all available time series metrics

Running Tests

npm test

License

MIT

Metrics Pipeline

The bowling analysis system processes keypoint data through a three-phase metrics pipeline:

• Phase One: Calculates biomechanical metrics using various calculators (angles, position, velocity, power, balance, etc.)
• Phase Two: Detects bowling events and calculates event-based metrics
• Phase Three: Generates higher-level metrics for technique, efficiency, consistency, and performance

Recent Improvements

The following improvements were made to the metrics pipeline:

• Enhanced error handling in all processors to ensure logging operations don't throw errors
• Fixed the calculators to directly return metrics with realistic values:
  • Updated AngleCalculator to return proper angle metrics
  • Updated BalanceCalculator to return balance-related metrics
  • Updated PowerCalculator to return power metrics
  • Updated PositionCalculator to return position metrics
• Improved the metrics merging process to ensure all metrics are included in the final output
• Fixed time series data handling to correctly generate and merge time series
• Enhanced validation and reporting to ensure complete metrics output
• Consolidated redundant code to improve maintainability (see CODEBASE_CLEANUP.md)
• Unified BiasCalculator implementation to replace multiple deprecated implementations

Usage

To run the metrics pipeline:

node run.js <keypoint_file> <output_file> [bias_file]

Example:

node run.js keypoint.json complete_metrics.json bias.json

The output file will contain:

• Metrics for each category (angles, position, velocity, etc.)
• Detected events (release point, foot landings, etc.)
• Time series data for visualization
• Analysis of the bowling technique
• Bias data for event detection