RACE/STAR Paper Code

Analysis code for the RACE/STAR paper on athletic ageing relative to a performance envelope. Athletes are represented by STAR coordinates in Functional Ageing Space (level, tempo, and timing when identifiable); the relative longevity index is only a derived projection of tempo.

This repository is a reproducible R analysis project (not an R package). Shared functions live in R/, numbered scripts in scripts/, and TMB sources in tmb/.

Paper materials cite this repository: https://github.com/idaejin/race-star-code

Repository Layout

R/                 Shared R functions for STAR fitting and simulation
scripts/           Numbered analysis pipeline scripts
tmb/               TMB C++ model sources; compiled objects are not tracked
data/              Lightweight data inputs used by the scripts
outputs/           Generated results, figures, and logs; ignored by Git
manuscript/        Optional manuscript references; ignored by Git except README
DESCRIPTION        R dependency metadata
vignettes/         Reproducibility walkthrough
LICENSE            MIT

Requirements

Install R and the packages listed in DESCRIPTION. The primary paper pipeline uses:

• dplyr, readr, tidyr, ggplot2, patchwork, scales
• gamlss, gamlss.dist
• TMB, RcppEigen
• nloptr, lme4
• expectreg, scam, quantreg, mgcv, gridExtra

Optional archived mixture utilities also use mclust.

install.packages(c(
  "dplyr", "readr", "tidyr", "ggplot2", "patchwork", "scales",
  "gamlss", "gamlss.dist", "TMB", "RcppEigen", "nloptr", "lme4",
  "expectreg", "scam", "quantreg", "mgcv", "gridExtra"
))
# optional (archived mixture scripts only):
# install.packages("mclust")

TMB scripts compile the C++ files in tmb/ locally when run.

Rscript scripts/00_check_environment.R

Detailed walkthrough: vignettes/reproduce-paper-analysis.Rmd.

Primary pipeline (matches the paper)

Stage1 envelope and Stage2 single-MVN STAR fits:

Rscript scripts/02_fit_envelopes_gamlss.R
Rscript scripts/05_fit_star_tmb.R
Rscript scripts/06_plot_star_trajectories.R
Rscript scripts/12_plot_combined_trajectories.R
Rscript scripts/13_plot_identifiability_geometry.R

Sensitivity / diagnostics used in the supplement:

Rscript scripts/11_bootstrap_envelope_star.R
Rscript scripts/15_envelope_engine_robustness.R

Simulation study (main-text Questions 1–3):

SIM_QUICK=1 SIM_B=10 SIM_N=80 Rscript scripts/14_run_simulation_study.R

For the full factorial, increase SIM_B and SIM_N (several hours).

Other scripts (01_, 03_, 04_, …) are extras or legacy paths retained for sensitivity checks.

Optional / archived (not in the paper)

Finite-mixture / latent-class STAR scripts are not part of the submitted paper narrative. They remain available for follow-up work:

Rscript scripts/07_mclust_star_blups.R
Rscript scripts/08_fit_star_lc_nlme.R
Rscript scripts/10_fit_star_lc_bolt.R

Generated Files

The outputs/ tree is created by the scripts and is intentionally ignored by Git, except for placeholder .gitkeep files. TMB shared libraries, object files, logs, rendered figures, and manuscript PDFs are also ignored.

Citation

If you use this code, cite the associated paper and this repository (see CITATION.cff).

License

MIT — see LICENSE.