πŸš΄β€β™‚οΈ PACE-VIEW: Explainable Cycling Intelligence Dashboard

PACE-VIEW turns raw TCX rides into decision-ready insights for athletes and coaches. It combines physics-informed modeling, digital-twin prediction, and explainable AI in one interactive dashboard.

πŸ’ͺ Why PACE-VIEW?

  • Dashboard-first workflow: Inspect workload, HR zone mix, efficiency trends, and per-session explanations in one place.

  • Explainability by design: Use counterfactual analysis, rationale generation, and pattern mining to understand why a session felt hard or easy.

  • Physics + ML pipeline: Quantify wind/terrain/environmental load and compare expected vs observed physiology.

  • Modular architecture: Run the full web app or use components independently in scripts.

πŸ“¦ Installation

Install PACE-VIEW with pip:

pip install pace_view

To install from source:

git clone https://github.com/firefly-cpp/pace_view.git
cd pace_view
poetry build
python setup.py build

↗️ Quick Start

Run the full dashboard:

python examples/full_dashboard.py

Then open an activity to view detailed explanations and decision-support outputs.

  • Free software: MIT license

  • Python versions: 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x

  • Documentation: https://pace-view.readthedocs.io/en/latest/

  • Tested OS: Windows, Ubuntu, Fedora, Alpine, Arch, macOS (This does not imply it will not work on others.)

✨ Implemented Components

PACE-VIEW architecture

Component 1: Data Ingestion & Preprocessing

Loads raw activity and weather signals, aligns timestamps, and builds clean dataframes for downstream modeling.

Classes/modules:

  • DataParser (pace_view/data_parsing.py)

  • DataCleaner (pace_view/data_cleaning.py)

Component 2: Environmental Quantification

Quantifies external/mechanical load and learns expected physiological behavior from historical rides.

Classes/modules:

  • PhysicsEngine (pace_view/physics.py)

  • DigitalTwinModel (pace_view/digital_twin.py)

Component 3: Explainable AI (XAI)

Explains deviations with counterfactual reasoning, generates human-readable rationales, and mines global patterns.

Classes/modules:

  • CounterfactualAnalyzer (pace_view/counterfactual.py)

  • RationaleGenerator (pace_view/rationale.py)

  • PatternMiner (pace_view/mining.py)

Component 4: Interactive Dashboard & Decision Support

Exposes session-level explanation and inter-session analysis through the web UI and example views.

Classes/modules:

  • ContextTrainer (pace_view/core.py)

  • Flask/Dash app: examples/full_dashboard.py

πŸ““ Examples

Run these from the repository root:

  1. Full Dashboard

    python examples/full_dashboard.py

    Runs the full interactive dashboard with all cards and activity detail routing. End-to-end example combining visualization and contextual explanations.

  2. Activity Detail Page

    python examples/activity_detail_page_example.py

    Serves only the activity detail page for a single example TCX activity.

  3. ContextTrainer (CLI Text Example)

    python examples/context_trainer_text_example.py

    Runs ContextTrainer without Flask or Dash and prints text-only results to the terminal.

  4. HR Zone Mix Card

    python examples/hr_zone_mix_example.py

    Demonstrates the zone-distribution visualization in isolation.

  5. Efficiency Over Time Card

    python examples/efficiency_over_time_example.py

    Shows how rolling-window controls affect the efficiency plot.

  6. HR vs Speed x Duration Heatmap

    python examples/hr_vs_speed_duration_example.py

    Demonstrates the binned relationship between duration, speed, and heart rate.

Repository Structure

  • pace_view/ - Core pipeline modules

  • data/ - Sample TCX files for local testing

  • tests/ - Pytest unit tests

  • scripts/ - Local helpers and experiments

  • assets/ - Images and supporting artifacts

Core Components Overview

  • pace_view/data_parsing.py - Loads TCX files and optional weather context

  • pace_view/data_cleaning.py - Builds aligned dataframes

  • pace_view/physics.py - Computes headwind, gradient, and virtual power

  • pace_view/digital_twin.py - Predicts expected HR and drift

  • pace_view/counterfactual.py - Counterfactual explanations

  • pace_view/rationale.py - Human-readable rationales

  • pace_view/mining.py - Mines interpretable rules using NiaARM

Data Flow (High Level)

  1. Parse TCX β†’ activity arrays + weather

  2. Clean + align β†’ dataframe

  3. Physics features β†’ headwind, gradient, virtual power

  4. Digital twin β†’ predicted HR and drift

  5. Counterfactual + rationale β†’ explanation output

  6. Pattern mining β†’ global rules across rides

Testing

Run from repository root:

python -m pytest -q

Using a specific interpreter:

<path/to/your/python/>python.exe -m pytest -q

Configuration (Weather API)

To enable weather enrichment, provide an API key via environment variables:

WEATHER_API_KEY=<your_key_here>

Examples using ContextTrainer resolve the key centrally via pace_view.config.get_weather_api_key().

The method checks:

  • Process environment variables

  • A project-root .env file (if present)

Optional manual loading using python-dotenv:

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv("WEATHER_API_KEY")

πŸ”‘ License

This package is distributed under the MIT License:

http://www.opensource.org/licenses/MIT

Disclaimer

This framework is provided as-is. There are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk.

πŸ“– Further Reading

πŸ“ References

Fister Jr, I., Fister, I., Iglesias, A., Galvez, A., Deb, S., & Fister, D. (2021). On deploying the Artificial Sport Trainer into practice. arXiv preprint: https://arxiv.org/abs/2109.13334

Fister Jr, I., Salcedo-Sanz, S., Iglesias, A., Fister, D., GΓ‘lvez, A., & Fister, I. (2021). New Perspectives in the Development of the Artificial Sport Trainer. Applied Sciences, 11(23), 11452.

DOI: https://doi.org/10.3390/app112311452