Merge pull request #16 from HzaCode/review-fixes-v1.0.2

v1.0.2: runnable vignettes, sample datasets, styler formatting

Author: HzaCode

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Athlytics
 Title: Academic R Package for Sports Physiology Analysis from Local 'Strava' Data
-Version: 1.0.1
+Version: 1.0.2
 Author: Zhiang He [aut, cre]
 Maintainer: Zhiang He <ang@hezhiang.com>
 Authors@R: 
@@ -39,10 +39,7 @@ Suggests:
     testthat (>= 3.0.0),
     mockery,
     rStrava,
-    xml2,
-    FITfileR
-Remotes:
-    grimbough/FITfileR
+    xml2
 VignetteBuilder: knitr
 RoxygenNote: 7.3.3
 Roxygen: list(markdown = TRUE)

NAMESPACE

@@ -11,6 +11,7 @@ export(athlytics_palette_science)
 export(athlytics_palette_vibrant)
 export(calculate_acwr)
 export(calculate_acwr_ewma)
+export(calculate_cohort_reference)
 export(calculate_decoupling)
 export(calculate_ef)
 export(calculate_ef_from_stream)
@@ -30,9 +31,13 @@ export(plot_pbs)
 export(plot_with_reference)
 export(quality_summary)
 export(scale_athlytics)
+export(summarize_quality)
 export(theme_athlytics)
 import(ggplot2)
 importFrom(dplyr,"%>%")
+importFrom(dplyr,across)
+importFrom(dplyr,all_of)
+importFrom(dplyr,any_of)
 importFrom(dplyr,arrange)
 importFrom(dplyr,bind_rows)
 importFrom(dplyr,case_when)
@@ -48,6 +53,7 @@ importFrom(dplyr,last)
 importFrom(dplyr,lead)
 importFrom(dplyr,left_join)
 importFrom(dplyr,mutate)
+importFrom(dplyr,n)
 importFrom(dplyr,pull)
 importFrom(dplyr,recode)
 importFrom(dplyr,rename)
@@ -69,6 +75,7 @@ importFrom(ggplot2,ggplot)
 importFrom(ggplot2,labs)
 importFrom(ggplot2,scale_color_viridis_d)
 importFrom(ggplot2,scale_x_date)
+importFrom(ggplot2,scale_y_continuous)
 importFrom(ggplot2,theme)
 importFrom(ggplot2,theme_minimal)
 importFrom(lubridate,as_date)
@@ -78,6 +85,7 @@ importFrom(lubridate,date)
 importFrom(lubridate,days)
 importFrom(lubridate,duration)
 importFrom(lubridate,floor_date)
+importFrom(lubridate,hms)
 importFrom(lubridate,interval)
 importFrom(lubridate,parse_date_time)
 importFrom(lubridate,period)
@@ -92,7 +100,9 @@ importFrom(purrr,quietly)
 importFrom(readr,cols)
 importFrom(readr,read_csv)
 importFrom(rlang,"%||%")
+importFrom(rlang,":=")
 importFrom(rlang,.data)
+importFrom(rlang,sym)
 importFrom(scales,pretty_breaks)
 importFrom(stats,median)
 importFrom(stats,na.omit)
@@ -104,6 +114,8 @@ importFrom(tidyr,pivot_longer)
 importFrom(tidyr,pivot_wider)
 importFrom(tidyr,unnest)
 importFrom(tools,toTitleCase)
+importFrom(utils,head)
 importFrom(utils,read.csv)
+importFrom(utils,tail)
 importFrom(zoo,rollapply)
 importFrom(zoo,rollmean)

NEWS.md

@@ -1,4 +1,16 @@
-# Athlytics 1.0.1
+# Athlytics 1.0.2
+ 
+## Documentation & Review Fixes
+ 
+* **Runnable vignettes**: Added executable demo chunks using built-in sample datasets so key plots render during `build_vignettes()`.
+ 
+* **Sample data naming**: Renamed built-in datasets from `athlytics_sample_*` to `sample_*` and updated docs/examples accordingly.
+ 
+* **Styling**: Ran `styler::style_pkg()` to improve formatting consistency.
+
+---
+
+# Athlytics 1.0.1
 
 ## Code Quality Improvements
 
@@ -8,6 +20,11 @@
 
 * **Documentation Fixes**: Fixed Rd line width issues in `plot_with_reference()` examples.
 
+* **API Naming Consistency**: Added verb-first primary APIs and kept previous names as deprecated wrappers for backward compatibility.
+  - New: `calculate_cohort_reference()` (replaces `cohort_reference()`)
+  - New: `summarize_quality()` (replaces `quality_summary()`)
+  - Old names remain available but emit a deprecation warning to guide migration.
+
 * **Build Configuration**: Updated `.Rbuildignore` to properly exclude development files.
 
 ---
@@ -81,12 +98,12 @@ For users upgrading from 0.1.x:
 
 ## Core Improvement: Enhanced Reliability & Testing with Simulated Data
 
-This significant update enhances package reliability and ease of use by integrating `athlytics_sample_data`. This enables all examples to run offline and ensures core functionalities have undergone more rigorous, reproducible testing.
+This significant update enhances package reliability and ease of use by integrating sample datasets. This enables all examples to run offline and ensures core functionalities have undergone more rigorous, reproducible testing.
 
 ## Key Changes
 
-*   **Examples & Vignettes**: All Roxygen examples and key vignette examples now primarily use `athlytics_sample_data` for offline execution and clarity. Network-dependent examples are clearly separated in `\donttest{}` blocks.
-*   **Test Suite**: Fundamentally refactored the test suite to extensively use `athlytics_sample_data` and `mockery`, improving test robustness and parameter coverage.
+*   **Examples & Vignettes**: All Roxygen examples and key vignette examples now primarily use sample datasets for offline execution and clarity. Network-dependent examples are clearly separated in `\donttest{}` blocks.
+*   **Test Suite**: Fundamentally refactored the test suite to extensively use sample datasets and `mockery`, improving test robustness and parameter coverage.
 *   **Strengthened Package Quality & Compliance**: Undertook thorough package validation, leading to key enhancements for overall robustness and adherence to R packaging standards. This involved: ensuring all **function examples** are correct and reliably executable (notably addressing `strava_oauth(...)` scenarios for offline/testing contexts); providing accurate and **refined documentation for data objects** in `R/data.R`; fixing **Roxygen import directives** for precise namespace definition; improving **help file readability** through Rd line width adjustments; and optimizing package data loading by adding `LazyData: true` to `DESCRIPTION`.
 *   **Documentation**: Minor improvements to documentation clarity and consistency (e.g., date formatting in plots, explicit naming of data frame arguments in examples).
 

R/Athlytics-package.R

@@ -0,0 +1,92 @@
+#' @keywords internal
+"_PACKAGE"
+
+#' Athlytics: Academic R Package for Sports Physiology Analysis
+#'
+#' @description
+#' Athlytics is an open-source computational framework for longitudinal analysis
+#' of exercise physiology metrics using local Strava data exports. Designed for
+#' personal analysis and sports science applications, this package provides
+#' standardized functions to calculate and visualize key physiological indicators.
+#'
+#' @section Main Functions:
+#' **Data Loading:**
+#' \itemize{
+#'   \item \code{\link{load_local_activities}}: Load activities from Strava export ZIP or directory
+#'   \item \code{\link{parse_activity_file}}: Parse individual FIT/TCX/GPX files
+#' }
+#'
+#' **Training Load Analysis:**
+#' \itemize{
+#'   \item \code{\link{calculate_acwr}}: Calculate Acute:Chronic Workload Ratio
+#'   \item \code{\link{calculate_acwr_ewma}}: ACWR using exponentially weighted moving averages
+#'   \item \code{\link{calculate_exposure}}: Calculate training load exposure metrics
+#' }
+#'
+#' **Physiological Metrics:**
+#' \itemize{
+#'   \item \code{\link{calculate_ef}}: Calculate Efficiency Factor (EF)
+#'   \item \code{\link{calculate_decoupling}}: Calculate cardiovascular decoupling
+#'   \item \code{\link{calculate_pbs}}: Calculate personal bests
+#' }
+#'
+#' **Visualization:**
+#' \itemize{
+#'   \item \code{\link{plot_acwr}}, \code{\link{plot_acwr_enhanced}}: Plot ACWR trends
+#'   \item \code{\link{plot_ef}}: Plot Efficiency Factor trends
+#'   \item \code{\link{plot_decoupling}}: Plot decoupling analysis
+#'   \item \code{\link{plot_exposure}}: Plot training load exposure
+#'   \item \code{\link{plot_pbs}}: Plot personal bests progression
+#' }
+#'
+#' **Quality Control & Cohort Analysis:**
+#' \itemize{
+#'   \item \code{\link{flag_quality}}: Flag activities based on quality criteria
+#'   \item \code{\link{summarize_quality}}: Summarize stream quality flags
+#'   \item \code{\link{calculate_cohort_reference}}: Generate cohort reference bands
+#' }
+#'
+#' @section Sample Datasets:
+#' The package includes simulated datasets for examples and testing:
+#' \itemize{
+#'   \item \code{\link{sample_acwr}}: Sample ACWR data
+#'   \item \code{\link{sample_ef}}: Sample Efficiency Factor data
+#'   \item \code{\link{sample_decoupling}}: Sample decoupling data
+#'   \item \code{\link{sample_exposure}}: Sample exposure data
+#'   \item \code{\link{sample_pbs}}: Sample personal bests data
+#' }
+#'
+#' @section Getting Started:
+#' ```
+#' library(Athlytics)
+#'
+#' # Load your Strava export
+#' activities <- load_local_activities("path/to/strava_export.zip")
+#'
+#' # Calculate ACWR
+#' acwr_data <- calculate_acwr(activities, activity_type = "Run")
+#'
+#' # Visualize
+
+#' plot_acwr(acwr_data)
+#' ```
+#'
+#' @seealso
+#' \itemize{
+#'   \item Package website: \url{https://hzacode.github.io/Athlytics/}
+#'   \item GitHub repository: \url{https://github.com/HzaCode/Athlytics}
+#'   \item Strava: \url{https://www.strava.com/}
+#' }
+#'
+#' @importFrom dplyr mutate filter select group_by ungroup summarise arrange
+#' @importFrom dplyr left_join bind_rows n lag lead across any_of all_of
+#' @importFrom ggplot2 ggplot aes geom_line geom_point geom_ribbon theme_minimal
+#' @importFrom ggplot2 labs scale_x_date scale_y_continuous theme element_text
+#' @importFrom lubridate as_date ymd hms seconds_to_period
+#' @importFrom rlang .data := sym
+#' @importFrom stats na.omit sd median quantile
+#' @importFrom utils head tail
+#'
+#' @name Athlytics-package
+#' @aliases Athlytics
+NULL