PaceMap AI

Project Overview

Runners track thousands of kilometres through GPS watches and apps, but raw GPX files rarely translate into actionable insight. PaceMap AI closes that gap with a Python pipeline that parses running data, visualises pace along the route, and trains machine learning models to predict finish times from distance, elevation, weather, and fatigue patterns.

The project combines sports analytics with practical ML engineering — from Haversine-based distance calculations and GPS smoothing through to model evaluation with MAE, RMSE, and R² metrics. It is built for runners who want to understand how terrain and conditions shape performance, not just record it.

The Problem

Most runners rely on post-run summaries from Strava or Garmin without tools to model how a specific route, elevation profile, or training load will affect race-day performance. Pace planning and finish-time estimation often stay manual, while GPS noise and inconsistent file formats make custom analysis difficult without a structured pipeline.

Key Features

• Interactive pace maps: Color-coded routes (fast, moderate, slow) with hoverable segment detail and start/finish markers, exported as interactive HTML maps.
• Finish-time prediction: Three ML models — Linear Regression, Random Forest, and Gradient Boosting — trained on distance, elevation, pace history, weather, and fatigue features.
• Feature engineering: Derived signals such as pace-per-elevation and distance × fatigue to capture how hills and endurance interact.
• Segment analytics: Kilometre-by-kilometre breakdowns, elevation gain, GPS smoothing, and pace charts over distance.
• Batch processing: Analyse multiple GPX files at once with validation for corrupted or incomplete uploads and CSV export for further study.
• Model diagnostics: Loss curves, feature-importance plots, and predicted-vs-actual scatter charts for validation and test sets.

How It Works

GPX files are parsed into track points, coordinates are smoothed to reduce GPS noise, and segment paces are calculated using the Haversine formula. Folium generates interactive maps; scikit-learn trains and compares models on engineered features. A 195-test pytest suite (96%+ coverage) covers parsing, pace calculation, visualisation, data loading, and ML modules.

Technologies Used

• Python 3.10+
• gpxpy for GPX parsing
• Folium for interactive map generation
• scikit-learn for Linear Regression, Random Forest, and Gradient Boosting
• pandas & NumPy for data processing
• matplotlib for pace charts and model visualisation
• pytest for automated testing (195 tests)

Results & Impact

The Gradient Boosting model achieves strong generalisation on held-out runs — example benchmarks include MAE around 89 seconds and R² above 0.91 on test data. Feature-importance analysis consistently ranks distance and elevation gain as the strongest predictors, with engineered fatigue and pace features adding meaningful signal.

v1.0 delivers end-to-end GPX analysis, ML-based race prediction, and production-grade test coverage. Active roadmap items include real-time race prediction, interval training analysis, and a future web dashboard.

Links