Introduction to Athlytics

library(Athlytics)
library(rStrava) # Required for authentication

Introduction

The Athlytics R package simplifies advanced analysis of athletic performance and training load using data sourced directly from the Strava API. It provides functions to fetch Strava data (via the rStrava package), calculate key metrics based on sports science principles, and generate insightful visualizations for training monitoring.

This vignette covers:

Installation

You can install the released version of Athlytics from CRAN (once available) with:

# install.packages("Athlytics")

Alternatively, install the development version from GitHub:

# install.packages('remotes') # If needed
# remotes::install_github('HzaCode/Athlytics')

Authentication with Strava

Athlytics requires a valid Strava API token to fetch data. This is handled using the rStrava package.

  1. Create a Strava API Application:
    • Go to https://developers.strava.com/ and navigate to “My API Application” under your settings, or follow their “Getting Started” guide to create an app.
    • Create an application (e.g., “My Athlytics App”).
    • Set “Authorization Callback Domain” to localhost.
    • Note your Client ID and Client Secret.
  2. Authenticate in R:
    • Use rStrava::strava_oauth().
    • Using cache = TRUE is highly recommended to securely store the token and avoid re-authenticating every session.
# --- Example Authentication Code ---
# (Do not run this block directly in the vignette build)

# Replace with your actual credentials or use environment variables
# app_name <- 'MyAthlyticsApp' 
# client_id <- "YOUR_CLIENT_ID" 
# client_secret <- "YOUR_SECRET"

# This function performs the OAuth handshake (may open browser)
# stoken <- rStrava::strava_oauth(
#   app_name,
#   client_id = client_id,
#   client_secret = client_secret,
#   app_scope = "activity:read_all", # Ensure necessary scopes
#   cache = TRUE # IMPORTANT: caches the token
# )

# For the examples below, we assume you have obtained a valid token
# object named 'stoken' in your interactive R session.
# Replace this placeholder line if running interactively:
stoken_placeholder <- "<Replace this string with your actual stoken object>"

# You would use the real 'stoken' object in function calls, e.g.:
# some_data <- calculate_acwr(stoken = stoken, ...)

Important: The following examples use stoken = stoken_placeholder and have eval=FALSE. You need to replace stoken_placeholder with your actual token object (stoken) and potentially set eval=TRUE if running interactively with a valid, cached token.

Example Analysis Visualizations

These functions generate plots to analyze trends and performance.

1. Load Exposure (Acute vs. Chronic)

Visualizes the relationship between short-term (acute) and long-term (chronic) training load to assess readiness and potential injury risk. Note that TSS/HRSS calculations based on activity summaries are approximations.

# Calculate using approximate TSS for Rides (Requires FTP)
exposure_data_tss <- calculate_exposure(
    stoken = stoken_placeholder, 
    activity_type = "Ride",
    load_metric = "tss",
    user_ftp = 280, # Example FTP, replace with yours
    acute_period = 7,
    chronic_period = 28
)

# Plot the result
plot_exposure(exposure_data = exposure_data_tss, risk_zones = TRUE)

# Calculate using approximate HRSS for Runs (Requires Max & Resting HR)
hrss_data <- calculate_exposure(
    stoken = stoken_placeholder,
    activity_type = "Run",
    load_metric = "hrss",
    user_max_hr = 190,     # Example Max HR
    user_resting_hr = 50, # Example Resting HR
    acute_period = 7,
    chronic_period = 42
)

plot_exposure(exposure_data = hrrss_data, risk_zones = TRUE)

2. ACWR Trend

Tracks the Acute:Chronic Workload Ratio over time, highlighting periods of potentially risky load increases.

# Calculate ACWR using duration for Runs
acwr_data_run <- calculate_acwr(
    stoken = stoken_placeholder,
    activity_type = "Run",
    load_metric = "duration_mins",
    acute_period = 7,
    chronic_period = 28
)

# Plot the trend
plot_acwr(acwr_data = acwr_data_run, highlight_zones = TRUE)

3. Efficiency Factor (EF) Trend

Monitors aerobic efficiency, typically calculated as output (Pace or Power) divided by input (Heart Rate). Requires activities with both relevant metrics.

# Calculate EF (Pace/HR) for Runs and Rides
ef_data_pacehr <- calculate_ef(
    stoken = stoken_placeholder,
    activity_type = c("Run", "Ride"),
    ef_metric = "Pace_HR"
)

# Plot the trend
plot_ef(ef_data = ef_data_pacehr, add_trend_line = TRUE)

4. Personal Bests (PBs)

Visualizes the progression of estimated best efforts over various distances (currently primarily for running).

Note: Fetching PB data can be slow and API-intensive.

# Calculate PBs for 1k, 5k, 10k Runs
# Limit activities checked for speed
pb_data_run <- calculate_pbs(
    stoken = stoken_placeholder,
    distance_meters = c(1000, 5000, 10000),
    activity_type = "Run",
    max_activities = 50 # Limit for example
)

# Plot the progression, highlighting new PBs
plot_pbs(pb_data = pb_data_run)

5. Decoupling Trend

Assesses cardiovascular drift during activities by comparing performance (Pace or Power) in the first half vs. the second half relative to Heart Rate.

Note: Fetching decoupling data now uses direct Strava API calls via httr (instead of rStrava::get_activity_streams) to obtain detailed activity streams. This can be very slow and may hit API rate limits more easily, especially for many activities. Consider using the max_activities parameter.

# Calculate Pace/HR decoupling for Runs
# Limit activities checked for speed
decoupling_data_run <- calculate_decoupling(
    stoken = stoken_placeholder,
    activity_type = "Run",
    decouple_metric = "Pace_HR",
    max_activities = 20 # Limit for example
)

# Plot the trend
plot_decoupling(decoupling_data = decoupling_data_run, add_trend_line = TRUE)

2. Strava API Setup

Further Information

This vignette provides a basic overview. For details on specific functions, their parameters, and underlying calculations, please consult the function help pages (e.g., ?calculate_acwr, ?plot_acwr) in R.

For bug reports or feature requests, please use the GitHub repository issues tracker: https://github.com/HzaCode/Athlytics/issues