UKBAnalytica: an integrated R package for scalable phenotyping and reproducible epidemiological analysis within the UK Biobank Research Analysis Platform

Technical Summary of UKBAnalytica

Problem Statement
The UK Biobank (UKB) offers a vast, longitudinal resource of approximately 500,000 participants with linked health records, genetic data, and multi-omics profiles. However, the richness of this data creates significant analytical bottlenecks. Researchers often face repetitive, fragmented workflows involving data cleaning, harmonization of multi-source disease endpoints (e.g., ICD-10/9, self-reports, death registries, OPCS-4 codes), distinction between prevalent and incident cases, and the construction of survival-ready cohorts. While existing tools like ukbtools, PHESANT, and FastUKB address specific aspects such as local file management, phenome-wide scans, or RAP-oriented extraction, there remains a lack of an integrated, lightweight, phenotype-driven framework that connects endpoint definition directly to survival cohort construction and downstream epidemiological or machine-learning analysis within the secure Research Analysis Platform (RAP) environment.

Methodology
The authors developed UKBAnalytica, an extensible R package designed specifically for the UK Biobank RAP environment. The package operates on a phenotype-centered workflow, abstracting heterogeneous data sources into reusable objects to standardize the analytical pipeline.

1. Data Extraction and Preprocessing: The package includes functions (rap_extract_pheno, get_variable_info) to retrieve RAP phenotype fields. It provides 52 predefined baseline variables and 15 curated variable sets (covering 167 field entries) for demographics, biomarkers, lifestyle, and genetics, reducing manual recoding.
2. Multi-Source Phenotyping: A core feature is a built-in library of 331 curated disease definitions. These definitions integrate multiple evidence sources, including ICD-10/9, self-reported conditions, death registry records, OPCS-4 codes, cancer registry data, and algorithmically defined outcomes. Users can retrieve these via get_predefined_diseases() or construct custom definitions using create_disease_definition().
3. Cohort Construction: The build_survival_dataset() function processes disease records to distinguish prevalent from incident cases based on baseline assessment dates. It calculates follow-up time, assigns censoring status, and generates analysis-ready survival datasets, explicitly handling the temporal ordering required for prospective analysis.
4. Downstream Analysis Modules: The package offers a unified framework for:
   • Epidemiology: Baseline summaries (create_baseline_table), regression modeling (Cox, logistic, linear, GLM, GAM) via run_regression, subgroup/interaction analysis, and sensitivity analyses (e.g., lagged event exclusion).
   • Advanced Statistics: Multiple imputation (via mice), propensity score matching/weighting, and causal mediation analysis.
   • Machine Learning: End-to-end workflows (ukb_ml_flow) for classification and survival modeling (including XGBoost, Random Forests, Cox models) with hyperparameter tuning, cross-validation, and SHAP-based interpretability.
   • Visualization: Publication-ready graphics for forest plots, Kaplan-Meier curves, ROC/PR curves, and SHAP plots.
5. AI Integration: The package includes a provider-agnostic "skill pack" of 14 reusable agent skills to assist researchers in writing analysis code while enforcing strict data privacy protocols (preventing AI agents from accessing individual-level RAP data).

Key Results
The utility of UKBAnalytica was demonstrated through an end-to-end case study on incident Chronic Obstructive Pulmonary Disease (COPD) using plasma proteomics data within the UK Biobank RAP.

• Cohort: The study analyzed 50,172 participants (2,427 incident COPD cases), split into training and internal validation sets.
• Proteomic Signatures: Cox regression identified 163 proteins significantly associated with incident COPD in the training set (Bonferroni-adjusted). The strongest signal was GDF15 (HR = 1.51). In the validation set, 69 proteins remained significant, with 63 overlapping the training set and 161 showing consistent directionality (Pearson r = 0.895).
• Biological Interpretation: Enrichment analysis linked these proteins to immune and inflammatory processes (e.g., innate immune response, complement activation). Protein-protein interaction networks identified four distinct functional clusters related to leukocyte activation and lipid metabolism.
• Predictive Modeling: An XGBoost model combining clinical covariates and proteomic data achieved the highest discrimination (AUC = 0.824), outperforming models using only proteins (AUC = 0.804) or only clinical variables (AUC = 0.800). SHAP analysis confirmed that the model prioritized biologically relevant proteins (e.g., GDF15, ADM, AGER).
• Risk Stratification: Calibrated risk scores effectively stratified participants into low, intermediate, and high-risk groups, with hazard ratios of 4.52 and 17.78 for intermediate and high-risk groups, respectively, compared to the low-risk group.
• Robustness: Sensitivity analyses (excluding early events, adjusting for smoking, excluding asthma) confirmed the stability of the protein-COPD associations.

Significance and Claims
The authors position UKBAnalytica not as a replacement for existing tools but as a complementary, integrated framework that bridges the gap between data extraction and complex modeling.

• Reproducibility and Transparency: By abstracting disease definitions and standardizing cohort construction, the package reduces repetitive scripting and ensures consistent endpoint definitions across studies.
• Workflow Efficiency: It connects phenotype curation directly to statistical and machine-learning modeling within a single R environment, eliminating the need to rebuild model-specific input files.
• Biological Validity: The COPD case study demonstrated that the framework can recover biologically credible signals (e.g., surfactant protein D, AGER, CEACAM6) consistent with prior literature, validating its utility for biomarker-driven research.
• Accessibility: The package is freely available, includes extensive documentation, and is designed to facilitate reproducible RAP-based biomedical research without requiring local data downloads.

The paper concludes that UKBAnalytica provides a practical, extensible, and phenotype-oriented solution for researchers seeking to conduct transparent, end-to-end analyses of UK Biobank data in secure cloud environments.