{"id":32200796,"url":"https://github.com/hzacode/athlytics","last_synced_at":"2025-10-22T03:55:52.539Z","repository":{"id":285703937,"uuid":"955421200","full_name":"HzaCode/Athlytics","owner":"HzaCode","description":"🏃  An R package for advanced sports performance analysis and training load monitoring using Strava data.","archived":false,"fork":false,"pushed_at":"2025-10-21T00:19:29.000Z","size":26693,"stargazers_count":30,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-22T03:55:46.038Z","etag":null,"topics":["activity-tracking","acute-chronic-workload-ratio","aerobic-decoupling","cohort-analysis","efficiency-factor","endurance-training","ewma","exercise-physiology","ggplot2","gpx-tcx-fit","rolling-average","sports-analytics","tidyverse","training-load","trimp"],"latest_commit_sha":null,"homepage":"https://hezhiang.com/Athlytics/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HzaCode.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","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-03-26T15:59:51.000Z","updated_at":"2025-10-21T16:27:43.000Z","dependencies_parsed_at":"2025-07-24T18:05:48.431Z","dependency_job_id":"00dfe4cf-fae1-4e45-b608-825716389e45","html_url":"https://github.com/HzaCode/Athlytics","commit_stats":null,"previous_names":["hzacode/athlytics"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/HzaCode/Athlytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HzaCode%2FAthlytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HzaCode%2FAthlytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HzaCode%2FAthlytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HzaCode%2FAthlytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HzaCode","download_url":"https://codeload.github.com/HzaCode/Athlytics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HzaCode%2FAthlytics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280376550,"owners_count":26320276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"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":["activity-tracking","acute-chronic-workload-ratio","aerobic-decoupling","cohort-analysis","efficiency-factor","endurance-training","ewma","exercise-physiology","ggplot2","gpx-tcx-fit","rolling-average","sports-analytics","tidyverse","training-load","trimp"],"created_at":"2025-10-22T03:55:51.055Z","updated_at":"2025-10-22T03:55:52.532Z","avatar_url":"https://github.com/HzaCode.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"analysis_output/logo.png\" alt=\"Athlytics logo\" width=\"220\"/\u003e\n\n# Athlytics\n*An offline, reproducible R toolkit for endurance-exercise data: from FIT/TCX/GPX \u0026 Strava archives to validated models (ACWR, EF, pa:hr decoupling, PB, exposure), with built-in QC and uncertainty estimation.*\n\n\u003cp\u003e\n📘 \u003ca href=\"https://hezhiang.com/Athlytics/\"\u003e\u003cstrong\u003eDocs\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n📦 \u003ca href=\"https://cran.r-project.org/package=Athlytics\"\u003e\u003cstrong\u003eCRAN\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n🐞 \u003ca href=\"https://github.com/HzaCode/Athlytics/issues\"\u003e\u003cstrong\u003eIssues\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://cran.r-project.org/package=Athlytics\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/CRAN-Accepted-blue?style=flat-square\" alt=\"CRAN\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://cran.r-project.org/web/views/SportsAnalytics.html\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/CRAN%20Listed-Sports%20Analytics-orange?style=flat-square\" alt=\"CRAN Listed\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://cran.r-project.org/package=Athlytics\"\u003e\n    \u003cimg src=\"https://cranlogs.r-pkg.org/badges/grand-total/Athlytics?style=flat-square\" alt=\"CRAN downloads (total)\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://hzacode.r-universe.dev/Athlytics\"\u003e\n    \u003cimg src=\"https://hzacode.r-universe.dev/badges/Athlytics\" alt=\"R-Universe\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/HzaCode/Athlytics/actions/workflows/R-CMD-check.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/HzaCode/Athlytics/R-CMD-check.yml?style=flat-square\u0026label=R-CMD-check\" alt=\"R-CMD-check\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/gh/HzaCode/Athlytics\"\u003e\n    \u003cimg src=\"https://img.shields.io/codecov/c/github/HzaCode/Athlytics?style=flat-square\" alt=\"Coverage\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"MIT License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/firefly-cpp/awesome-computational-intelligence-in-sports?tab=readme-ov-file#software-\"\u003e\n    \u003cimg src=\"https://awesome.re/badge-flat.svg\" alt=\"Awesome list\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://docs.ropensci.org/pkgcheck/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/rOpenSci-pkgcheck-brightgreen?style=flat-square\" alt=\"rOpenSci pkgcheck\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/HzaCode/Athlytics\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/code%20quality-A-brightgreen?style=flat-square\" alt=\"Code Quality\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.repostatus.org/#active\"\u003e\n    \u003cimg src=\"https://www.repostatus.org/badges/latest/active.svg?style=flat-square\" alt=\"Project Status: Active\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003e\u003cstrong\u003e🚀 Quick Start\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003ca href=\"#-core-analyses\"\u003e\u003cstrong\u003e📊 Core Analyses\u003c/strong\u003e\u003c/a\u003e \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003ca href=\"#-citation\"\u003e\u003cstrong\u003e📝 Citation\u003c/strong\u003e\u003c/a\u003e\n\u003c/h3\u003e\n\n\n\u003c/div\u003e\n\n\n## 🎯 Overview\n\n**Athlytics** is a research-oriented R package for the longitudinal analysis of endurance training. It operates entirely on **local Strava exports** (or FIT/TCX/GPX files), avoiding API dependencies to ensure **privacy** and long-term **reproducibility**.\n\nThe package standardizes the workflow from data ingestion and quality control to model estimation and uncertainty quantification. Implemented endpoints include **acute-to-chronic workload ratio (ACWR)**, **aerobic efficiency (EF)**, and **cardiovascular decoupling (pa:hr)**, alongside personal-best and exposure profiles suitable for **single-subject** and **cohort** designs. All functions return tidy data, facilitating statistical modeling and figure generation for academic reporting.\n\n\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"man/figures/Athlytics_Final.png\" alt=\"Athlytics overview diagram\" width=\"900\"\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\n\n\n## ✨ Key Features\n\n*   ✅ **Reproducible by design** – Fully offline; no API keys. Deterministic pipelines suitable for longitudinal studies.\n*   ✅ **Validated metrics** – Implements ACWR, EF, and decoupling commonly used in exercise physiology; integrated **QC** checks.\n*   ✅ **Uncertainty-aware** – Functions return estimates with variance/intervals where applicable, enabling principled inference.\n*   ✅ **Cohort support** – Built-in helpers for multi-athlete datasets and percentile-band references.\n*   ✅ **Tidy outputs** – Consistent, analysis-ready tibbles for downstream modeling and figure pipelines.\n\n---\n\n## 📦 Installation\n\n**1. Stable Release (CRAN)**\n```r\ninstall.packages(\"Athlytics\")\n```\n*Note: The CRAN version may not include the latest features like direct ZIP file support.*\n\n**2. R-Universe**\n```r\n# Enable repository from r-universe\noptions(repos = c(\n  hzacode = 'https://hzacode.r-universe.dev'))\n\n# Install Athlytics\ninstall.packages('Athlytics')\n```\n\n**3. Development Version (GitHub - Recommended)**\n```r\n# First, install remotes if you don't have it\n# install.packages(\"remotes\")\n\n# Install the latest development version from GitHub\nremotes::install_github(\"HzaCode/Athlytics\")\n```\n\n---\n### 🚀 Quick Start\n\n\n### 📥 Step 1: Export Your Strava Data\n\n1.  Navigate to **[Strava Settings → My Account](https://www.strava.com/settings/profile)**.\n2.  Under \"Download or Delete Your Account,\" click **\"Get Started\"** and then **\"Request Your Archive\"**.\n3.  You'll receive an email with a download link — this may take some time.\n4.  Download the ZIP file (e.g., `export_12345678.zip`). **There is no need to unzip it.**\n\n### 💻 Step 2: Load and Analyze (Cohort Example)\n\nThis example shows a common workflow: loading data for several athletes, calculating their training load, and comparing one athlete to the group average.\n\n```r\nlibrary(Athlytics)\nlibrary(dplyr)\n\n# 1. Load data for a cohort of athletes, adding unique IDs\nathlete1 \u003c- load_local_activities(\"path/to/athlete1_export.zip\") %\u003e% mutate(athlete_id = \"A1\")\nathlete2 \u003c- load_local_activities(\"path/to/athlete2_export.zip\") %\u003e% mutate(athlete_id = \"A2\")\ncohort_data \u003c- bind_rows(athlete1, athlete2)\n\n# 2. Calculate ACWR for each athlete in the cohort\ncohort_acwr \u003c- cohort_data %\u003e%\n  group_by(athlete_id) %\u003e%\n  group_modify(~ calculate_acwr(.x, activity_type = \"Run\", load_metric = \"duration_mins\")) %\u003e%\n  ungroup()\n\n# 3. Generate percentile bands to serve as a reference for the cohort\nreference_bands \u003c- cohort_reference(cohort_acwr, metric = \"acwr_smooth\")\n\n# 4. Plot an individual's data against the cohort reference bands\nindividual_acwr \u003c- cohort_acwr %\u003e% filter(athlete_id == \"A1\")\nplot_with_reference(individual = individual_acwr, reference = reference_bands)\n```\n\n---\n\n## 📊 Core Analyses\n\nAll functions return clean, tidy `tibble` data frames, making it easy to perform your own custom analysis or visualizations.\n\n### 1️⃣ Training Load Monitoring (ACWR)\nTrack how your training load is progressing to avoid ramping up too quickly, which can help in managing injury risk.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"analysis_output/01b_acwr_multi_group.png\" alt=\"ACWR Analysis\" width=\"750\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\u003ca href=\"https://hezhiang.com/Athlytics/reference/calculate_acwr.html\"\u003eLearn more about ACWR analysis...\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n### 2️⃣ Aerobic Efficiency (EF)\nSee how your aerobic fitness is changing over time by comparing your output (pace or power) to your effort (heart rate). A rising trend is a great sign of improving fitness.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"analysis_output/02b_ef_multi_group.png\" alt=\"Efficiency Factor\" width=\"750\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\u003ca href=\"https://hezhiang.com/Athlytics/reference/calculate_ef.html\"\u003eLearn more about Aerobic Efficiency...\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n### 3️⃣ Cardiovascular Decoupling\nMeasure your endurance by analyzing how much your heart rate \"drifts\" upward during a steady-state workout. A low decoupling rate (\u003c5%) is a marker of excellent aerobic conditioning.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"analysis_output/05b_decoupling_multi_group.png\" alt=\"Decoupling Analysis\" width=\"750\"/\u003e\n  \u003cbr\u003e\n  \u003cem\u003e\u003ca href=\"https://hezhiang.com/Athlytics/reference/calculate_decoupling.html\"\u003eLearn more about Decoupling...\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\n## 📐 Methods \u0026 Validation\n\nThis release implements widely used constructs in endurance-exercise analytics:\n- **ACWR**: rolling acute (e.g., 7-day) vs chronic (e.g., 28-day) load ratios with smoothing options.\n- **Aerobic Efficiency (EF)**: output (pace/power) relative to effort (heart rate) over time.\n- **Cardiovascular Decoupling (pa:hr)**: drift between pace/power and heart rate during steady efforts.\n\nWe provide input validation, outlier handling, and activity-level QC filters (e.g., minimal duration, HR plausibility ranges). For cohort summarization, Athlytics computes percentile bands and supports stratification by sport, sex, or other covariates when available.\n\n---\n\n## 📝 Citation\n\nIf you use **Athlytics** in academic work, please cite the software as well as the original methodological sources for specific metrics.\n\n```bibtex\n@software{athlytics2025,\n  title   = {Athlytics: A Reproducible Framework for Endurance Data Analysis},\n  author  = {Zhiang He},\n  year    = {2025},\n  version = {1.0.0},\n  url     = {https://github.com/HzaCode/Athlytics}\n}\n```\n\n---\n\n## ⚖️ Ethical Considerations\n\nAthlytics processes personal training records. Ensure appropriate consent for cohort analyses, de-identify outputs where required, and comply with local IRB/ethics and data-protection regulations.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our [CONTRIBUTING.md](CONTRIBUTING.md) guide and follow our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n*   **🐛 Report an Issue**: [Open an Issue](https://github.com/HzaCode/Athlytics/issues)\n*   **💡 Suggest a Feature**: [Start a Discussion](https://github.com/HzaCode/Athlytics/discussions)\n*   **🔧 Submit a Pull Request**: We appreciate your help in improving Athlytics.\n\n---\n\n## 🙏 Acknowledgements\n\nWe thank the [pyOpenSci](https://www.pyopensci.org/) community, [Prof. Benjamin S. Baumer](https://github.com/beanumber), and [Prof. Iztok Fister Jr.](https://github.com/firefly-cpp) for their valuable feedback and suggestions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhzacode%2Fathlytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhzacode%2Fathlytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhzacode%2Fathlytics/lists"}