Metadata-Version: 2.3
Name: pace_view
Version: 0.1.0
Summary: Explainable Cycling Intelligence Dashboard
Author: Sebastian Pack
Author-email: sebastian.pack@tugraz.at
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: docs
Requires-Dist: myst-parser ; extra == "docs"
Requires-Dist: sphinx ; extra == "docs"
Requires-Dist: sphinx-rtd-theme ; extra == "docs"
Description-Content-Type: text/markdown

<h1 align="center">
🚴‍♂️ PACE-VIEW: Explainable Cycling Intelligence Dashboard
</h1>

<p align="center">
  <img alt="PyPI Version" src="https://img.shields.io/pypi/v/pace-view.svg" href="https://pypi.python.org/pypi/pace-view">
  <img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/pace-view.svg">
  <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/pace-view.svg">
  <img alt="Fedora package" src="https://img.shields.io/fedora/v/python3-pace-view?color=blue&label=Fedora%20Linux&logo=fedora" href="https://src.fedoraproject.org/rpms/python-pace-view">
  <img alt="AUR package" src="https://img.shields.io/aur/version/python-pace-view?color=blue&label=Arch%20Linux&logo=arch-linux" href="https://aur.archlinux.org/packages/python-pace-view">
  <img alt="Packaging status" src="https://repology.org/badge/tiny-repos/python:pace-view.svg" href="https://repology.org/project/python:pace-view/versions">
  <img alt="GitHub license" src="https://img.shields.io/github/license/firefly-cpp/pace-view.svg" href="https://github.com/firefly-cpp/pace-view/blob/master/LICENSE">
  <img alt="Documentation Status" src="https://readthedocs.org/projects/pace-view/badge/?version=latest" href="https://pace-view.readthedocs.io/en/latest/?badge=latest">
</p>

<p align="center">
  <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/firefly-cpp/pace-view">
  <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/w/firefly-cpp/pace-view.svg">
  <img alt="Average time to resolve an issue" src="http://isitmaintained.com/badge/resolution/firefly-cpp/pace-view.svg" href="http://isitmaintained.com/project/firefly-cpp/pace-view">
  <img alt="Percentage of issues still open" src="http://isitmaintained.com/badge/open/firefly-cpp/pace-view.svg" href="http://isitmaintained.com/project/firefly-cpp/pace-view">
</p>

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
```

In case you want to install directly from the source code, use:

```
git clone https://github.com/firefly-cpp/pace_view.git
cd pace_view
poetry 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/](https://pace-view.readthedocs.io/en/latest/)
- **Tested** OS: Windows, Ubuntu, Fedora, Alpine, Arch, macOS. **However, that does not mean it does not work on others**

## ✨ Implemented Components
![PACE-VIEW architecture](.github/img/architecture.png)

### Component 1: Data Ingestion & Preprocessing
This component loads raw activity and weather signals, aligns timestamps, and builds clean dataframes for downstream modeling.  
Classes/modules: `DataParser` ([pace_view/data_parsing.py](pace_view/data_parsing.py)), `DataCleaner` ([pace_view/data_cleaning.py](pace_view/data_cleaning.py)).

### Component 2: Environmental Quantification
This component quantifies external/mechanical load and learns expected physiological behavior from historical rides.  
Classes/modules: `PhysicsEngine` ([pace_view/physics.py](pace_view/physics.py)), `DigitalTwinModel` ([pace_view/digital_twin.py](pace_view/digital_twin.py)).

### Component 3: XAI
This component explains deviations with counterfactual reasoning, generates human-readable rationales, and mines global patterns.  
Classes/modules: `CounterfactualAnalyzer` ([pace_view/counterfactual.py](pace_view/counterfactual.py)), `RationaleGenerator` ([pace_view/rationale.py](pace_view/rationale.py)), `PatternMiner` ([pace_view/mining.py](pace_view/mining.py)).

### Component 4: Interactive Dashboard & Decision Support
This component exposes session-level explanation and inter-session analysis through the web UI and example views.  
Classes/modules: `ContextTrainer` ([pace_view/core.py](pace_view/core.py)) plus the Flask/Dash app in [examples/full_dashboard.py](examples/full_dashboard.py).

## 📓 Examples

Run these from the repository root:

1. `python examples/full_dashboard.py`  
   Runs the full interactive dashboard with all cards and activity detail routing. It is the end-to-end example that combines visualization and contextual explanations.

2. `python examples/activity_detail_page_example.py`  
   Serves only the activity detail page for a single example TCX activity. It demonstrates the detail view with ContextTrainer output but without the full dashboard.

3. `python examples/context_trainer_text_example.py`  
   Runs ContextTrainer without Flask or Dash and prints text-only results to the terminal. It demonstrates model fitting, pattern mining, and single-activity explanation in CLI form.

4. `python examples/hr_zone_mix_example.py`  
   Shows only the HR Zone Mix card with period controls. It demonstrates the zone-distribution visualization in isolation.

5. `python examples/efficiency_over_time_example.py`  
   Shows only the Efficiency Over Time card with rolling-window controls. It demonstrates how trend window changes affect the efficiency plot.

6. `python examples/hr_vs_speed_duration_example.py`  
   Shows only the HR vs Speed x Duration heatmap card. It 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

- `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` and `pace_view/rationale.py` build explanations
- `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 repo root:

```
python -m pytest -q
```

If you use a specific interpreter:

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

## Configuration (Weather API)

If you want weather enrichment, provide an API key via environment variables:

```
WEATHER_API_KEY=<your_key_here>
```

Examples using `ContextTrainer` now resolve the key centrally via `pace_view.config.get_weather_api_key()`.
It checks the process environment first and also loads a project-root `.env` file if present.

Optional manual loading with `python-dotenv`:

```
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv("WEATHER_API_KEY")
```


## 🖼️ Dashboard Preview

These screenshots show the main views provided by the example dashboard and activity detail page.

### Overview dashboard
![PACE-VIEW overview dashboard](.github/img/pace-view-dashboard-overview.png)
The main dashboard combines session-level summary cards, dataset metadata, an activity list, and quick access to detailed explanations for individual rides.

### HR Zone Mix
![PACE-VIEW HR zone mix visualization](.github/img/pace-view-dashboard-hr-zones.png)
This view summarizes how training time is distributed across heart-rate zones over a selectable time window.

### Efficiency Over Time
![PACE-VIEW efficiency over time visualization](.github/img/pace-view-dashboard-efficiency.png)
This chart tracks speed-per-heartbeat efficiency across sessions and overlays a rolling trend to make longer-term changes easier to spot.

### HR vs Speed x Duration
![PACE-VIEW HR vs speed x duration heatmap](.github/img/pace-view-dashboard-heatmap.png)
This heatmap highlights how average heart rate changes across combinations of ride duration and average speed.

### Single-activity explanation page
![PACE-VIEW single activity explanation page](.github/img/pace-view-single-activity.png)
The activity detail page brings together the digital twin conclusion, session metrics, and rationale cards that explain why a ride felt the way it did.


## 🔑 License

This package is distributed under the MIT License. This license can be found online
at <http://www.opensource.org/licenses/MIT>.

## Disclaimer

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

## 📖 Further read
[1] [Awesome Computational Intelligence in Sports](https://github.com/firefly-cpp/awesome-computational-intelligence-in-sports)

## 🔗 Related packages/frameworks

[1] [sport-activities-features: A minimalistic toolbox for extracting features from sports activity files written in Python](https://github.com/firefly-cpp/sport-activities-features)

[2] [ast-tdl: Training Description Language for Artificial Sport Trainer](https://github.com/firefly-cpp/ast-tdl)

[3] [NiaAML: A framework for Automated Machine Learning based on nature-inspired algorithms for optimization](https://github.com/firefly-cpp/niaaml)

## 📝 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 [arXiv:2109.13334](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: [10.3390/app112311452](https://doi.org/10.3390/app112311452)

## 🫂 Contributors

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

