plot_decoupling {Athlytics}R Documentation

Plot Aerobic Decoupling Trend

Description

Visualizes the trend of aerobic decoupling over time.

Usage

plot_decoupling(
  stoken,
  activity_type = c("Run", "Ride"),
  decouple_metric = c("Pace_HR", "Power_HR"),
  start_date = NULL,
  end_date = NULL,
  min_duration_mins = 45,
  max_activities = 50,
  add_trend_line = TRUE,
  smoothing_method = "loess",
  decoupling_df = NULL
)

Arguments

stoken

A valid Strava token from 'rStrava::strava_oauth()'. Required unless 'decoupling_df' is provided.

activity_type

Type(s) of activities to analyze (e.g., "Run", "Ride").

decouple_metric

Metric basis: "Pace_HR" or "Power_HR".

start_date

Optional. Analysis start date (YYYY-MM-DD string or Date). Defaults to ~1 year ago.

end_date

Optional. Analysis end date (YYYY-MM-DD string or Date). Defaults to today.

min_duration_mins

Minimum activity duration (minutes) to include. Default 45.

max_activities

Max number of recent activities to fetch/analyze when 'stoken' is used. Default 50.

add_trend_line

Add a smoothed trend line ('geom_smooth')? Default 'TRUE'.

smoothing_method

Smoothing method for trend line (e.g., "loess", "lm"). Default "loess".

decoupling_df

Optional. A pre-calculated data frame from 'calculate_decoupling'. If provided, 'stoken' and other calculation parameters are ignored. Must contain 'date' and 'decoupling' columns.

Details

Plots the aerobic decoupling trend over time. Uses pre-calculated data or calls 'calculate_decoupling' (can be slow).

Plots decoupling percentage ((EF_1st_half - EF_2nd_half) / EF_1st_half * 100). Positive values mean HR drifted relative to output. A 5 used as reference. If 'decoupling_df' is not provided, calls 'calculate_decoupling' first (can be slow and hit API limits).

Value

A ggplot object showing the decoupling trend.

Examples

# Example using simulated data
data(Athlytics_sample_data)
# Explicitly name decoupling_df and provide activity_type
if (!is.null(athlytics_sample_decoupling) && nrow(athlytics_sample_decoupling) > 0) {
  p <- plot_decoupling(decoupling_df = athlytics_sample_decoupling, activity_type = "Run")
  print(p)
}

## Not run: 
# Example using real data (requires authentication)
# NOTE: The following rStrava::strava_oauth call is a placeholder.
# You MUST replace placeholders with your actual Strava API credentials.
tryCatch({
  stoken_example <- rStrava::strava_oauth(
    app_name = "YOUR_APP_NAME_PLACEHOLDER",
    app_client_id = "YOUR_CLIENT_ID_PLACEHOLDER",     # CORRECTED
    app_secret = "YOUR_CLIENT_SECRET_PLACEHOLDER",  # CORRECTED
    cache = TRUE,
    app_scope = "activity:read_all" # Recommended scope
  )

  if (inherits(stoken_example, "Token2.0")) {
    message("Placeholder stoken_example created for Athlytics examples.")

    # Example 1: Plot Decoupling trend for Runs (last 6 months)
    # This first calculates the data, then plots it.
    message("Calculating decoupling for Runs (last 6 months) - may take a moment...")
    decoupling_runs_6mo <- tryCatch({
        calculate_decoupling(
            stoken = stoken_example,
            activity_type = "Run",
            decouple_metric = "Pace_HR",
            date_range = c(format(Sys.Date() - lubridate::months(6), "%Y-%m-%d"), 
                           format(Sys.Date(), "%Y-%m-%d")),
            max_activities = 5 # Keep low for example
        )
    }, error = function(e_calc) {
        message(paste("Could not calculate decoupling data in example:", e_calc$message))
        return(dplyr::tibble()) # Return empty tibble on error
    })

    if (nrow(decoupling_runs_6mo) > 0 && "decoupling" %in% names(decoupling_runs_6mo)) {
      p_runs_6mo <- plot_decoupling(decoupling_df = decoupling_runs_6mo, activity_type = "Run")
      print(p_runs_6mo)
    } else {
      message("No decoupling data for Runs (last 6 months) to plot, or calculation failed.")
    }

    # Example 2: Plot Decoupling trend for Rides
    # decoupling_rides <- calculate_decoupling(
    #   stoken = stoken_example,
    #   activity_type = "Ride",
    #   decouple_metric = "Power_HR",
    #   max_activities = 5
    # )
    # if (nrow(decoupling_rides) > 0 && "decoupling" %in% names(decoupling_rides)) {
    #   p_rides <- plot_decoupling(decoupling_df = decoupling_rides, activity_type = "Ride")
    #   print(p_rides)
    # } else {
    #   message("No decoupling data for Rides to plot, or calculation failed.")
    # }

    # Example 3: Plot Decoupling trend for multiple Run types (no trend line)
    # decoupling_multi_run <- calculate_decoupling(
    #   stoken = stoken_example,
    #   activity_type = c("Run", "VirtualRun"),
    #   decouple_metric = "Pace_HR",
    #   max_activities = 5
    # )
    # if (nrow(decoupling_multi_run) > 0 && "decoupling" %in% names(decoupling_multi_run)) {
    #   p_multi_run <- plot_decoupling(
    #     decoupling_df = decoupling_multi_run,
    #     activity_type = c("Run", "VirtualRun"),
    #     add_trend_line = FALSE
    #   )
    #   print(p_multi_run)
    # } else {
    #   message("No decoupling data for multi-run types to plot, or calculation failed.")
    # }

  } else {
    message("Failed to create placeholder stoken for plot_decoupling examples.")
  }
}, error = function(e_auth) {
  message(paste("Error during rStrava authentication in example:", e_auth$message))
})

## End(Not run)

[Package Athlytics version 0.1.2 Index]