{"id":50468052,"url":"https://github.com/firefly-cpp/pace_view","last_synced_at":"2026-06-01T08:32:47.114Z","repository":{"id":286125692,"uuid":"960366542","full_name":"firefly-cpp/pace_view","owner":"firefly-cpp","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-30T20:19:19.000Z","size":43498,"stargazers_count":12,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-09T03:42:51.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firefly-cpp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-04T10:06:02.000Z","updated_at":"2026-03-03T23:20:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"11142689-b3ec-4f10-8da7-b2996c5af17c","html_url":"https://github.com/firefly-cpp/pace_view","commit_stats":null,"previous_names":["firefly-cpp/ast-monitor-ai","firefly-cpp/pedal"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/firefly-cpp/pace_view","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefly-cpp%2Fpace_view","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefly-cpp%2Fpace_view/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefly-cpp%2Fpace_view/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefly-cpp%2Fpace_view/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firefly-cpp","download_url":"https://codeload.github.com/firefly-cpp/pace_view/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firefly-cpp%2Fpace_view/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T08:32:47.026Z","updated_at":"2026-06-01T08:32:47.108Z","avatar_url":"https://github.com/firefly-cpp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n🚴‍♂️ PACE-VIEW: Explainable Cycling Intelligence Dashboard\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/pace-view.svg\" href=\"https://pypi.python.org/pypi/pace-view\"\u003e\n  \u003cimg alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/pace-view.svg\"\u003e\n  \u003cimg alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/pace-view.svg\"\u003e\n  \u003cimg alt=\"Fedora package\" src=\"https://img.shields.io/fedora/v/python3-pace-view?color=blue\u0026label=Fedora%20Linux\u0026logo=fedora\" href=\"https://src.fedoraproject.org/rpms/python-pace-view\"\u003e\n  \u003cimg alt=\"AUR package\" src=\"https://img.shields.io/aur/version/python-pace-view?color=blue\u0026label=Arch%20Linux\u0026logo=arch-linux\" href=\"https://aur.archlinux.org/packages/python-pace-view\"\u003e\n  \u003cimg alt=\"Packaging status\" src=\"https://repology.org/badge/tiny-repos/python:pace-view.svg\" href=\"https://repology.org/project/python:pace-view/versions\"\u003e\n  \u003cimg 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\"\u003e\n  \u003cimg alt=\"Documentation Status\" src=\"https://readthedocs.org/projects/pace-view/badge/?version=latest\" href=\"https://pace-view.readthedocs.io/en/latest/?badge=latest\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub repo size\" src=\"https://img.shields.io/github/repo-size/firefly-cpp/pace-view\"\u003e\n  \u003cimg alt=\"GitHub commit activity\" src=\"https://img.shields.io/github/commit-activity/w/firefly-cpp/pace-view.svg\"\u003e\n  \u003cimg 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\"\u003e\n  \u003cimg 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\"\u003e\n\u003c/p\u003e\n\nPACE-VIEW turns raw TCX rides into decision-ready insights for athletes and coaches.  \nIt combines physics-informed modeling, digital-twin prediction, and explainable AI in one interactive dashboard.\n\n### 💪 Why PACE-VIEW?\n- **Dashboard-first workflow**: inspect workload, HR zone mix, efficiency trends, and per-session explanations in one place.\n- **Explainability by design**: use counterfactual analysis, rationale generation, and pattern mining to understand *why* a session felt hard or easy.\n- **Physics + ML pipeline**: quantify wind/terrain/environmental load and compare expected vs observed physiology.\n- **Modular architecture**: run the full web app or use components independently in scripts.\n\n## 📦 Installation \nInstall PACE-VIEW with pip:\n\n```\npip install pace_view\n```\n\nIn case you want to install directly from the source code, use:\n\n```\ngit clone https://github.com/firefly-cpp/pace_view.git\ncd pace_view\npoetry build\n```\n\n### ↗️ Quick start\nRun the full dashboard:\n\n```\npython examples/full_dashboard.py\n```\n\nThen open an activity to view detailed explanations and decision-support outputs.\n\n- **Free software**: MIT license\n- **Python versions**: 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x\n- **Documentation**: [https://pace-view.readthedocs.io/en/latest/](https://pace-view.readthedocs.io/en/latest/)\n- **Tested** OS: Windows, Ubuntu, Fedora, Alpine, Arch, macOS. **However, that does not mean it does not work on others**\n\n## ✨ Implemented Components\n![PACE-VIEW architecture](.github/img/architecture.png)\n\n### Component 1: Data Ingestion \u0026 Preprocessing\nThis component loads raw activity and weather signals, aligns timestamps, and builds clean dataframes for downstream modeling.  \nClasses/modules: `DataParser` ([pace_view/data_parsing.py](pace_view/data_parsing.py)), `DataCleaner` ([pace_view/data_cleaning.py](pace_view/data_cleaning.py)).\n\n### Component 2: Environmental Quantification\nThis component quantifies external/mechanical load and learns expected physiological behavior from historical rides.  \nClasses/modules: `PhysicsEngine` ([pace_view/physics.py](pace_view/physics.py)), `DigitalTwinModel` ([pace_view/digital_twin.py](pace_view/digital_twin.py)).\n\n### Component 3: XAI\nThis component explains deviations with counterfactual reasoning, generates human-readable rationales, and mines global patterns.  \nClasses/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)).\n\n### Component 4: Interactive Dashboard \u0026 Decision Support\nThis component exposes session-level explanation and inter-session analysis through the web UI and example views.  \nClasses/modules: `ContextTrainer` ([pace_view/core.py](pace_view/core.py)) plus the Flask/Dash app in [examples/full_dashboard.py](examples/full_dashboard.py).\n\n## 📓 Examples\n\nRun these from the repository root:\n\n1. `python examples/full_dashboard.py`  \n   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.\n\n2. `python examples/activity_detail_page_example.py`  \n   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.\n\n3. `python examples/context_trainer_text_example.py`  \n   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.\n\n4. `python examples/hr_zone_mix_example.py`  \n   Shows only the HR Zone Mix card with period controls. It demonstrates the zone-distribution visualization in isolation.\n\n5. `python examples/efficiency_over_time_example.py`  \n   Shows only the Efficiency Over Time card with rolling-window controls. It demonstrates how trend window changes affect the efficiency plot.\n\n6. `python examples/hr_vs_speed_duration_example.py`  \n   Shows only the HR vs Speed x Duration heatmap card. It demonstrates the binned relationship between duration, speed, and heart rate.\n\n## Repository Structure\n\n- `pace_view/` core pipeline modules\n- `data/` sample TCX files for local testing\n- `tests/` pytest unit tests\n- `scripts/` local helpers and experiments\n- `assets/` images and supporting artifacts\n\n## Core Components\n\n- `pace_view/data_parsing.py` loads TCX files and optional weather context\n- `pace_view/data_cleaning.py` builds aligned dataframes\n- `pace_view/physics.py` computes headwind, gradient, and virtual power\n- `pace_view/digital_twin.py` predicts expected HR and drift\n- `pace_view/counterfactual.py` and `pace_view/rationale.py` build explanations\n- `pace_view/mining.py` mines interpretable rules using NiaARM\n\n## Data Flow (high level)\n\n1. Parse TCX -\u003e activity arrays + weather\n2. Clean + align -\u003e dataframe\n3. Physics features -\u003e headwind, gradient, virtual power\n4. Digital twin -\u003e predicted HR and drift\n5. Counterfactual + rationale -\u003e explanation output\n6. Pattern mining -\u003e global rules across rides\n\n## Testing\n\nRun from repo root:\n\n```\npython -m pytest -q\n```\n\nIf you use a specific interpreter:\n\n```\n\u003cpath/to/your/python/\u003epython.exe -m pytest -q\n```\n\n## Configuration (Weather API)\n\nIf you want weather enrichment, provide an API key via environment variables:\n\n```\nWEATHER_API_KEY=\u003cyour_key_here\u003e\n```\n\nExamples using `ContextTrainer` now resolve the key centrally via `pace_view.config.get_weather_api_key()`.\nIt checks the process environment first and also loads a project-root `.env` file if present.\n\nOptional manual loading with `python-dotenv`:\n\n```\nfrom dotenv import load_dotenv\nimport os\nload_dotenv()\napi_key = os.getenv(\"WEATHER_API_KEY\")\n```\n\n\n## 🖼️ Dashboard Preview\n\nThese screenshots show the main views provided by the example dashboard and activity detail page.\n\n### Overview dashboard\n![PACE-VIEW overview dashboard](.github/img/pace-view-dashboard-overview.png)\nThe main dashboard combines session-level summary cards, dataset metadata, an activity list, and quick access to detailed explanations for individual rides.\n\n### HR Zone Mix\n![PACE-VIEW HR zone mix visualization](.github/img/pace-view-dashboard-hr-zones.png)\nThis view summarizes how training time is distributed across heart-rate zones over a selectable time window.\n\n### Efficiency Over Time\n![PACE-VIEW efficiency over time visualization](.github/img/pace-view-dashboard-efficiency.png)\nThis chart tracks speed-per-heartbeat efficiency across sessions and overlays a rolling trend to make longer-term changes easier to spot.\n\n### HR vs Speed x Duration\n![PACE-VIEW HR vs speed x duration heatmap](.github/img/pace-view-dashboard-heatmap.png)\nThis heatmap highlights how average heart rate changes across combinations of ride duration and average speed.\n\n### Single-activity explanation page\n![PACE-VIEW single activity explanation page](.github/img/pace-view-single-activity.png)\nThe activity detail page brings together the digital twin conclusion, session metrics, and rationale cards that explain why a ride felt the way it did.\n\n\n## 🔑 License\n\nThis package is distributed under the MIT License. This license can be found online\nat \u003chttp://www.opensource.org/licenses/MIT\u003e.\n\n## Disclaimer\n\nThis 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!\n\n## 📖 Further read\n[1] [Awesome Computational Intelligence in Sports](https://github.com/firefly-cpp/awesome-computational-intelligence-in-sports)\n\n## 🔗 Related packages/frameworks\n\n[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)\n\n[2] [ast-tdl: Training Description Language for Artificial Sport Trainer](https://github.com/firefly-cpp/ast-tdl)\n\n[3] [NiaAML: A framework for Automated Machine Learning based on nature-inspired algorithms for optimization](https://github.com/firefly-cpp/niaaml)\n\n## 📝 References\n\nFister Jr, I., Fister, I., Iglesias, A., Galvez, A., Deb, S., \u0026 Fister, D. (2021). On deploying the Artificial Sport\nTrainer into practice. arXiv preprint [arXiv:2109.13334](https://arxiv.org/abs/2109.13334).\n\nFister Jr, I., Salcedo-Sanz, S., Iglesias, A., Fister, D., Gálvez, A., \u0026 Fister, I. (2021). New Perspectives in the\nDevelopment of the Artificial Sport Trainer. Applied Sciences, 11(23), 11452.\nDOI: [10.3390/app112311452](https://doi.org/10.3390/app112311452)\n\n## 🫂 Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirefly-cpp%2Fpace_view","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirefly-cpp%2Fpace_view","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirefly-cpp%2Fpace_view/lists"}