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:

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

Recent Improvements

The following improvements were made to the metrics pipeline:

1. Enhanced error handling in all processors to ensure logging operations don't throw errors
2. 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
3. Improved the metrics merging process to ensure all metrics are included in the final output
4. Fixed time series data handling to correctly generate and merge time series
5. Enhanced validation and reporting to ensure complete metrics output
6. Consolidated redundant code to improve maintainability (see CODEBASE_CLEANUP.md)
7. 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