Package {UKBAnalytica}

Title:	UK Biobank Data Processing and Survival Analysis Toolkit
Version:	1.0.0
Author:	Nan He [aut, cre]
Maintainer:	Nan He <hinna01@163.com>
Description:	Provides an integrated workflow for UK Biobank Research Analysis Platform (RAP) hosted and RAP-generated analysis tables. The package supports RAP phenotype extraction planning, predefined variable sets and disease definitions, standardized baseline preprocessing, multi-source endpoint ascertainment, prevalent and incident case classification, survival-ready cohort construction, regression, multiple imputation, propensity score analysis, mediation analysis, subgroup and sensitivity analyses, machine learning, proteomics enrichment and protein-protein interaction analysis, and publication-oriented visualization. The package workflow is described in He et al. (2026) <doi:10.64898/2026.06.19.26356057>.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
URL:	https://github.com/Hinna0818/UKBAnalytica, https://hinna0818.github.io/UKBAnalytica/
BugReports:	https://github.com/Hinna0818/UKBAnalytica/issues
Imports:	data.table, stringi, ggplot2, rlang, scales, survival, pROC, tableone, mice, mitools, sandwich, lmtest, MASS, mgcv, xml2, igraph
Suggests:	testthat, rms, gbm, cobalt, survminer, MatchIt, regmedint, ranger, xgboost, glmnet, e1071, nnet, rpart, Boruta, rBayesianOptimization, randomForestSRC, clusterProfiler, AnnotationDbi, org.Hs.eg.db, qs2
Config/testthat/edition:	3
Config/Needs/bioc:	TRUE
Depends:	R (≥ 4.0)
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-06-24 04:06:19 UTC; hinna
Repository:	CRAN
Date/Publication:	2026-06-30 11:00:07 UTC

UKBAnalytica: UK Biobank Data Processing and Survival Analysis Toolkit

Description

A high-performance R package for processing UK Biobank (UKB) Research Analysis Platform (RAP) data exports. Designed for epidemiological studies requiring efficient extraction of diagnosis records and generation of survival analysis datasets.

Details

Core Capabilities:

• Parse ICD-10/ICD-9 diagnosis codes from mixed-format data

• Parse OPCS4 operative procedure codes from hospital summary operations

• Process self-reported illness data with fractional year conversion

• Integrate death registry data as diagnosis sources

• Generate Cox regression-ready survival datasets

• Support flexible data source selection for sensitivity analyses

Key Functions:

• parse_icd10_diagnoses: Extract ICD-10 hospital diagnoses

• parse_icd9_diagnoses: Extract ICD-9 hospital diagnoses

• parse_opcs4_procedures: Extract OPCS4 hospital procedures

• parse_self_reported_illnesses: Extract self-reported conditions

• parse_death_records: Extract death registry data

• build_survival_dataset: Generate survival analysis data

• extract_cases_by_source: Flexible source-specific extraction

UKB Data Fields:

• ICD-10: p41270 (codes) + p41280_a* (dates)

• ICD-9: p41271 (codes) + p41281_a* (dates)

• OPCS4: p41272 (codes) + p41282_a* (dates)

• Self-report: p20002_i*_a* (codes) + p20008_i*_a* (years)

• Death: p40001/p40002 (causes) + p40000 (dates)

Author(s)

Maintainer: Nan He hinna01@163.com (ORCID)

References

UK Biobank Data Showcase: https://biobank.ndph.ox.ac.uk/showcase/

See Also

Useful links:

• https://github.com/Hinna0818/UKBAnalytica

• https://hinna0818.github.io/UKBAnalytica/

• Report bugs at https://github.com/Hinna0818/UKBAnalytica/issues

Calculate model baseline

Description

Calculate model baseline

Usage

.calculate_baseline(object)

Check if ML package is available

Description

Check if ML package is available

Usage

.check_ml_package(pkg)

Create prediction wrapper for SHAP

Description

Create prediction wrapper for SHAP

Usage

.create_shap_predict_wrapper(object)

Fit Cox with Elastic Net

Description

Fit Cox with Elastic Net

Usage

.fit_coxnet(
  formula,
  data,
  time_var,
  event_var,
  predictor_vars,
  params,
  verbose,
  ...
)

Fit GBM Survival

Description

Fit GBM Survival

Usage

.fit_gbm_surv(
  formula,
  data,
  time_var,
  event_var,
  predictor_vars,
  params,
  verbose,
  ...
)

Fit GLMNet (Elastic Net)

Description

Fit GLMNet (Elastic Net)

Usage

.fit_glmnet(X, y, task, params, verbose, ...)

Fit Logistic/Linear Regression

Description

Fit Logistic/Linear Regression

Usage

.fit_logistic(formula, data, task, params, verbose, ...)

Fit Neural Network

Description

Fit Neural Network

Usage

.fit_nnet(X, y, task, params, verbose, ...)

Fit Random Forest

Description

Fit Random Forest

Usage

.fit_rf(X, y, task, params, verbose, ...)

Fit Random Survival Forest

Description

Fit Random Survival Forest

Usage

.fit_rsf(formula, data, params, verbose, ...)

Fit SVM

Description

Fit SVM

Usage

.fit_svm(X, y, task, params, verbose, ...)

Fit XGBoost

Description

Fit XGBoost

Usage

.fit_xgboost(X, y, task, params, verbose, ...)

Get model type label

Description

Get model type label

Usage

.get_model_label(model)

Get processor function for a variable

Description

Get processor function for a variable

Usage

.get_processor(var_name)

Get default variable to UKB field ID mapping

Description

Get default variable to UKB field ID mapping

Usage

.get_variable_mapping()

Value

A named list with variable mappings

Parse formula to get response and predictors

Description

Parse formula to get response and predictors

Usage

.parse_formula(formula, data)

Prepare model matrix

Description

Prepare model matrix

Usage

.prepare_model_data(formula, data, task)

Split data into train/test

Description

Split data into train/test

Usage

.split_data(data, y, split_ratio, stratify, seed)

Aggregate Earliest Cancer Registry Diagnosis Date

Description

Computes the earliest cancer registry diagnosis date for each participant-disease combination.

Usage

aggregate_cancer_registry_earliest(cancer_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Aggregate Death as Diagnosis Source

Description

Uses death date as diagnosis date for participants who died from the target condition.

Usage

aggregate_death_as_diagnosis(death_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Aggregate Earliest ICD-10 Diagnosis Date Per Participant

Description

Computes the earliest diagnosis date for each participant-disease combination. Essential for determining incident vs prevalent cases in survival analysis.

Usage

aggregate_icd10_earliest(icd10_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Aggregate Earliest ICD-9 Diagnosis Date Per Participant

Description

Computes the earliest diagnosis date for each participant-disease combination.

Usage

aggregate_icd9_earliest(icd9_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Aggregate Earliest OPCS4 Procedure Date Per Participant

Description

Computes the earliest procedure date for each participant-disease combination.

Usage

aggregate_opcs4_earliest(opcs4_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Aggregate Earliest Self-Report Date Per Participant

Description

Computes the earliest self-reported diagnosis date for each participant-disease combination.

Usage

aggregate_self_report_earliest(sr_filtered)

Arguments

Value

A data.table with columns: eid, disease, earliest_date, source.

Assess Covariate Balance

Description

Assess balance of covariates between treatment groups before and after matching or weighting.

Usage

assess_balance(
  data,
  treatment,
  covariates,
  method = c("unmatched", "matched", "weighted"),
  weight_col = NULL,
  threshold = 0.1
)

Arguments

Value

A data.frame with balance statistics:

variable

Variable name

mean_treated

Mean in treatment group

mean_control

Mean in control group

smd

Standardized mean difference

variance_ratio

Variance ratio (treated/control)

balanced

Whether SMD < threshold

Build Full Cohort Survival Dataset

Description

Extends build_survival_dataset to include non-cases (controls) for each disease, creating a complete cohort for survival analysis.

Usage

build_full_cohort(
  dt,
  disease_definitions,
  prevalent_sources = c("ICD10", "ICD9", "Self-report", "Death"),
  outcome_sources = c("ICD10", "ICD9", "Death"),
  censor_date = as.Date("2023-10-31"),
  baseline_col = "p53_i0",
  primary_disease = NULL,
  exclude_prevalent = TRUE,
  dt_threads = NULL
)

Arguments

Value

A data.table with complete cohort survival data.

Build Survival Analysis Dataset

Description

Integrates diagnosis data from multiple sources (ICD-10, ICD-9, self-report, death, OPCS4 procedures, cancer registry records, First Occurrence fields, algorithm) to generate a survival dataset. By default, returns a wide table that retains all participants and adds disease history/incident indicators plus follow-up time for a primary disease.

Usage

build_survival_dataset(
  dt,
  disease_definitions,
  prevalent_sources = c("ICD10", "ICD9", "Self-report", "Death"),
  outcome_sources = c("ICD10", "ICD9", "Death"),
  censor_date = as.Date("2023-10-31"),
  baseline_col = "p53_i0",
  time_skeleton = NULL,
  primary_disease = NULL,
  output = c("wide", "long"),
  include_all = TRUE,
  show_flow = TRUE,
  dt_threads = NULL
)

Arguments

Details

This function supports separate source definitions for prevalent case exclusion and outcome ascertainment. This is important because:

• Self-reported conditions at baseline clearly indicate pre-existing disease and should be used for prevalent case identification.

• However, self-reported incident events during follow-up have imprecise dates (year only) and lower validity, making them unsuitable for outcome definition.

• OPCS4 procedure dates are often useful for procedure-defined endpoints or surgical history, but may occur later than the true biological disease onset.

Case classification logic:

• Prevalent case: Earliest diagnosis date (from prevalent_sources) <= baseline date. These participants have outcome_status = NA and outcome_surv_time = NA because they are not at risk for incident disease.

• Incident case: Earliest diagnosis date (from outcome_sources) > baseline date

• Censored: No diagnosis by end of follow-up (status = 0)

Follow-up time calculation (controlled by primary_disease):

• Prevalent case (primary disease): NA (not at risk)

• Incident case: (diagnosis_date - baseline_date) / 365.25

• Censored: (min(death_date, censor_date) - baseline_date) / 365.25

Value

A data.table with columns:

eid

Participant identifier

<Disease>_history

1 if prevalent case (from prevalent_sources), 0 otherwise

<Disease>_incident

1 if incident case (from outcome_sources), 0 otherwise

outcome_status

Event indicator for primary disease (1=event, 0=censored, NA=prevalent case)

outcome_surv_time

Follow-up time in years for primary disease (NA for prevalent cases)

Calculate air pollution exposure averages

Description

Computes averaged air pollution exposures from multiple time points.

Usage

calculate_air_pollution(df, pollutants = c("NO2", "PM10", "PM2.5", "NOx"))

Arguments

Value

A data.table with averaged pollution columns

Calculate blood pressure from multiple readings

Description

Combines automated and manual BP readings using UK Biobank collection logic: automated readings are primary and manual readings are used as fallback when automated measurements are unavailable. Returns the mean of the two available readings.

Usage

calculate_blood_pressure(
  df,
  type = c("sbp", "dbp"),
  prefer = c("auto", "manual")
)

Arguments

Value

A data.table with calculated sbp or dbp column added

Calculate diet score

Description

Computes a simplified healthy diet score based on food frequency questionnaire.

Usage

calculate_diet_score(
  df,
  components = c("fruit", "vegetable", "fish", "meat", "cereal", "milk"),
  na_handling = c("strict", "partial")
)

Arguments

Value

A data.table with diet_score column (0-7 scale)

Calculate IPTW Weights

Description

Calculate inverse probability of treatment weights (IPTW) for causal inference.

Usage

calculate_weights(
  data,
  ps_col = "ps",
  treatment,
  weight_type = c("ATE", "ATT", "ATC"),
  stabilized = TRUE,
  truncate = c(0.01, 0.99)
)

Arguments

Details

Weight formulas:

• ATE: T/PS + (1-T)/(1-PS)

• ATT: T + (1-T) * PS/(1-PS)

• ATC: T * (1-PS)/PS + (1-T)

Stabilized weights multiply by the marginal probability of treatment.

Value

A data.table with the original data plus:

weight

IPTW weight

Classify UK Biobank metabolite names

Description

Classify metabolite-like names into broad groups used by the metabolomics ORA workflow. Small molecules can be mapped to MetaboAnalyst-compatible names, whereas lipoprotein subclass measures, lipid aggregate measures, and proteins are retained in the mapping table but are not passed to small-molecule ORA by default.

Usage

classify_metabolites(metabolites)

Arguments

Value

A data.frame with metabolite, category, and metaboanalyst_name.

Examples

classify_metabolites(c("Alanine", "LDL Cholesterol", "Apolipoprotein B"))

Extract Coefficients from Mediation Results

Description

Extract effect estimates from mediation analysis results.

Usage

## S3 method for class 'mediation_result'
coef(object, ...)

Arguments

Value

A data.frame with effect estimates.

Combine Multiple Disease Definitions

Description

Merges multiple disease definitions into a single composite endpoint definition. Useful for creating MACE (Major Adverse Cardiovascular Events) or similar composite outcomes.

Usage

combine_disease_definitions(..., name = "Combined")

Arguments

Value

A combined disease definition object.

Compare Case Counts Across Data Sources

Description

Generates a summary table comparing case counts from different data sources. Useful for methods sections and sensitivity analysis planning.

Usage

compare_data_sources(dt, disease_definitions, baseline_col = "p53_i0")

Arguments

Value

A data.table with case counts by source and combination.

Compute topological metrics for a PPI network

Description

A thin wrapper around TCMDATA::compute_nodeinfo().

Usage

compute_protein_ppi_metrics(
  ppi,
  weight_attr = "score",
  normalize = FALSE,
  seed = 42
)

Arguments

Value

An igraph object with additional vertex attributes.

Confidence Intervals for Mediation Results

Description

Extract confidence intervals from mediation analysis results.

Usage

## S3 method for class 'mediation_result'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

Value

A matrix with lower and upper confidence limits.

Create a baseline table comparing cases and controls under different conditions.

Description

Create a baseline table comparing cases and controls under different conditions.

Usage

create_baseline_table(
  data,
  case_col,
  factor_cols = NULL,
  continuous_cols = NULL,
  test = FALSE
)

Arguments

Value

a list containing table one information.

References

https://github.com/kaz-yos/tableone

Create Disease Definition Object

Description

Helper function to create a standardized disease definition object containing ICD-10/ICD-9 patterns, self-report codes, UK Biobank First Occurrence fields, and optionally a UK Biobank algorithmically-defined outcome date field.

Usage

create_disease_definition(
  name = NULL,
  icd10_pattern = NULL,
  icd9_pattern = NULL,
  sr_codes = NULL,
  death_icd10 = NULL,
  opcs4_pattern = NULL,
  first_occurrence_fields = NULL,
  first_occurrence_source_fields = NULL,
  cancer_icd10_pattern = NULL,
  cancer_histology = NULL,
  cancer_behaviour = NULL,
  algo_date_field = NULL,
  algo_source_field = NULL,
  icd10 = NULL,
  icd9 = NULL,
  self_report = NULL
)

Arguments

Value

A list containing the disease definition parameters.

Create an imputationList Object

Description

Converts a list of data.frames to a imputationList object for use with mitools functions.

Usage

create_imputation_list(datasets, validate = TRUE)

Arguments

Value

An imputationList object.

Create a medication definition object

Description

Helper for defining medication code sets from UK Biobank self-reported treatment/medication fields. The first implementation focuses on field 20003 arrays and intentionally stores only medication codes and classes, not copied source codelist descriptions.

Usage

create_medication_definition(
  name,
  codes,
  source = "Self-report 20003",
  field_id = 20003L,
  medication_class = NULL,
  match_type = "exact"
)

Arguments

Value

A list describing the medication definition.

Examples

bp <- create_medication_definition("Any BP medication", c(1, 2, 3))

Estimate Propensity Score

Description

Calculate propensity scores using logistic regression or gradient boosting.

Usage

estimate_propensity_score(
  data,
  treatment,
  covariates,
  method = c("logistic", "gbm"),
  formula = NULL
)

Arguments

Value

A data.table with the original data plus:

ps

Propensity score (probability of treatment)

Extract Cases by Specified Data Sources

Description

Flexibly extracts disease cases using user-specified data sources. Enables main analysis with strict case definitions (e.g., ICD-10 only) and sensitivity analyses with broader definitions (e.g., all sources).

Usage

extract_cases_by_source(
  dt,
  disease_definitions,
  sources = c("ICD10", "ICD9", "Self-report", "Death"),
  censor_date = as.Date("2023-10-31"),
  baseline_col = "p53_i0"
)

Arguments

Details

This function is designed for epidemiological studies requiring:

• Main analysis with hospital-confirmed diagnoses only

• Sensitivity analyses including self-reported conditions

• Procedure-augmented definitions for surgical phenotypes using OPCS4

• Cancer registry ascertainment for malignant neoplasm endpoints

• First Occurrence fields for UKB's pre-mapped 3-character ICD-10 outcomes

• Source-specific case counts for methods reporting

• UK Biobank algorithmically-defined outcomes for validated case ascertainment

The "Algorithm" source reads date fields from UK Biobank Category 42 (Algorithmically-defined outcomes). These are pre-computed by the UK Biobank outcome adjudication group, combining self-report, hospital admissions, and death records with high positive predictive value. Records with date 1900-01-01 are excluded (date unknown). If a source field is available in the definition, it is propagated into diagnosis_source as "Algorithm_<source_code>".

The "FirstOccurrence" source reads singular UKB fields such as p131298_i0 or p131298 for I21 first reported. Values with UKB special date coding 819 (1900-01-01, 1901-01-01, 1902-02-02, 1903-03-03, 1909-09-09, and 2037-07-07) are excluded.

Value

A data.table with case-level survival data from specified sources.

Extract Baseline Diabetes Subtypes (T1DM/T2DM) with HbA1c Support

Description

Extracts baseline prevalent Type 1 and Type 2 diabetes using existing source-based disease history logic, and optionally augments Type 2 classification using baseline HbA1c.

Usage

extract_diabetes_subtype_baseline(
  dt,
  disease_definitions = NULL,
  sources = c("ICD10", "ICD9", "Self-report"),
  baseline_col = "p53_i0",
  hba1c_col = "p30750_i0",
  hba1c_threshold = 48,
  include_hba1c = TRUE
)

Arguments

Details

This is a baseline classification helper and does not redefine incident event logic. Type 1 has priority when both T1 and T2 evidence are present.

Value

A data.table with columns:

eid

Participant identifier

T1DM_history

Baseline prevalent T1DM from selected sources (0/1)

T2DM_history

Baseline prevalent T2DM from selected sources (0/1)

diabetes_hba1c

Baseline HbA1c diabetes flag (0/1/NA)

T2DM_history_enhanced

T2DM from source history OR HbA1c criterion (0/1)

Diabetes_history

Any baseline diabetes (T1DM or enhanced T2DM) (0/1)

diabetes_subtype

"Type1", "Type2", or "No_diabetes"

Extract participant-level disease diagnosis status

Description

Defines whether each participant has a selected disease using one or more UK Biobank evidence sources. This is the recommended public helper when the goal is disease ascertainment rather than construction of a full survival cohort. For survival-ready endpoints, use build_survival_dataset.

Usage

extract_disease_diagnosis(
  dt,
  disease,
  disease_definitions = NULL,
  sources = c("ICD10", "ICD9", "Self-report", "Death"),
  censor_date = as.Date("2023-10-31"),
  baseline_col = "p53_i0",
  include_all = TRUE
)

Arguments

Value

A data.table with participant-level diagnosis status, first diagnosis date, diagnosis source, prevalent and incident indicators, and survival fields returned by extract_cases_by_source where available.

Extract Disease History (Prevalent Cases) for Covariates

Description

Extracts prevalent case status (diagnosed before baseline) for specified diseases. Designed for use as covariates in sensitivity analyses or covariate adjustment. Returns a wide-format table with one binary column per disease.

Usage

extract_disease_history(
  dt,
  diseases,
  disease_definitions = NULL,
  sources = "ICD10",
  baseline_col = "p53_i0"
)

Arguments

Details

This function is specifically designed for extracting covariate data in epidemiological studies. Common use cases:

• Adjusting for baseline comorbidities in Cox regression

• Sensitivity analyses with different case definitions

• Creating propensity score matching variables

The function only returns history (prevalent) columns, not incident columns, to clearly separate covariate extraction from outcome definition.

Value

A data.table with columns:

eid

Participant identifier

Disease_history

1 if prevalent case, 0 otherwise (one column per disease)

Extract Disease History with Multiple Source Comparisons

Description

Extracts prevalent case status from multiple data source combinations simultaneously for sensitivity analysis comparison. Returns a table with separate columns for each source definition.

Usage

extract_disease_history_sensitivity(
  dt,
  diseases,
  disease_definitions = NULL,
  baseline_col = "p53_i0"
)

Arguments

Value

A data.table with columns:

eid

Participant identifier

Disease_history_ICD10

Prevalent case using ICD-10 only

Disease_history_hospital

Prevalent case using ICD-10 + ICD-9

Disease_history_all

Prevalent case using all sources

Extract medication use from UKB drug fields

Description

Processes medication fields (6177 for male, 6153 for female) to extract specific medication categories.

Usage

extract_medications(
  df,
  medications = c("cholesterol", "blood_pressure", "insulin")
)

Arguments

Value

A data.table with binary medication columns added (1=Yes, 0=No, NA=Missing)

Extract self-reported medication indicators from field 20003

Description

Matches UK Biobank treatment/medication code arrays (⁠p20003_i*_a*⁠) against predefined or user-supplied medication definitions and appends binary participant-level medication indicators.

Usage

extract_self_report_medications(
  data,
  medications = NULL,
  medication_definitions = get_predefined_medications(),
  id_col = "eid",
  instance = 0,
  prefix = "med20003",
  missing_as_zero = TRUE,
  return_long = FALSE
)

Arguments

Value

A data.table.

Examples

dat <- data.frame(
  eid = 1:3,
  p20003_i0_a0 = c("1140883066", "1140874686", NA),
  p20003_i0_a1 = c(NA, "1140851690", NA)
)
extract_self_report_medications(dat, medications = c("Insulin", "Metformin"))

Filter Cancer Registry Records by ICD-10 and Tumour Metadata

Description

Filters cancer registry records using ICD-10 pattern matching and optional tumour histology / behaviour constraints.

Usage

filter_cancer_registry(
  cancer_long,
  pattern,
  disease_label,
  histology = NULL,
  behaviour = NULL
)

Arguments

Value

A filtered data.table with an added disease column.

Filter Death Records by ICD-10 Code Pattern

Description

Filters death cause records using regular expression pattern matching.

Usage

filter_death_codes(death_long, pattern, disease_label)

Arguments

Value

A data.table with filtered records and added disease column.

Filter ICD-10 Records by Code Pattern

Description

Filters ICD-10 diagnosis records using regular expression pattern matching.

Usage

filter_icd10_codes(icd10_long, pattern, disease_label)

Arguments

Value

A data.table with filtered records and added disease column.

Filter ICD-9 Records by Code Pattern

Description

Filters ICD-9 diagnosis records using regular expression pattern matching.

Usage

filter_icd9_codes(icd9_long, pattern, disease_label)

Arguments

Value

A data.table with filtered records and added disease column.

Filter OPCS4 Procedure Records by Code Pattern

Description

Filters OPCS4 procedure records using regular expression pattern matching.

Usage

filter_opcs4_codes(opcs4_long, pattern, disease_label)

Arguments

Value

A data.table with filtered records and added disease column.

Filter Self-Reported Illness Records by Code

Description

Filters self-reported illness records by specific UKB illness codes.

Usage

filter_self_report_codes(sr_long, codes, disease_label)

Arguments

Details

Common UKB self-report codes:

• 1065: High blood pressure

• 1066: Heart attack

• 1067: Angina

• 1068: Stroke

• 1220: Diabetes

• 1076: Heart failure

Value

A data.table with filtered records and added disease column.

Fit Regression Models on Multiple Imputed Datasets

Description

Fits the specified regression model on each imputed dataset.

Usage

fit_mi_models(
  datasets,
  formula,
  model_type = c("lm", "logistic", "poisson", "cox", "negbin"),
  family = NULL,
  ...
)

Arguments

Value

A list of fitted model objects.

Generate Wide-Format with Dual Source Definition

Description

Internal function that generates wide-format disease status using separate sources for prevalent (history) and incident cases. This supports the common epidemiological practice of using self-report for baseline exclusion but not for outcome ascertainment.

Usage

generate_wide_format_dual_source(
  dt,
  disease_definitions,
  prevalent_sources,
  outcome_sources,
  censor_date,
  baseline_col,
  prevalent_long = NULL,
  outcome_long = NULL
)

Arguments

Value

A data.table with _history and _incident columns per disease.

Extract Death Dates for All Deceased Participants

Description

Returns death dates for all deceased participants, used for censoring in survival analysis.

Usage

get_death_dates(dt)

Arguments

Value

A data.table with columns: eid, death_date.

Query the built-in disease code catalog

Description

Returns a source-aware disease code catalog containing curated UKBAnalytica disease definitions and Pomegranate-derived UK Biobank phenotype coding definitions. This function returns tabular code metadata; it does not change the default behavior of get_predefined_diseases().

Usage

get_disease_catalog(
  source = c("all", "curated", "pomegranate"),
  disease = NULL,
  code_system = NULL,
  supported_only = FALSE
)

Arguments

Value

A data.frame.

Examples

copd_codes <- get_disease_catalog(disease = "copd")
head(copd_codes)

Get one UK Biobank field's metadata

Description

Convenience wrapper around get_field_metadata() for a single UKB field_id. This is the simplest way to ask "what does field 4080 correspond to?" and get a one-row metadata table back in R.

Usage

get_field_info(
  field_id,
  ukb_data_dict = NULL,
  dataset = NULL,
  fields_df = NULL,
  entity = "participant",
  live = FALSE,
  timeout = 30
)

Arguments

Value

A one-row data.frame when the field is found.

Get structured UK Biobank field metadata

Description

Returns a structured data.frame of UK Biobank field metadata. When ukb_data_dict is supplied, the function reads a UK Biobank data dictionary metadata file available in the current session and standardizes common metadata columns. When fields_df or a RAP dataset is supplied, the function also records the approved RAP field names available in the current project.

This is intended to be a simple entry point for users who want to inspect UKB field metadata in R before planning an extraction.

Usage

get_field_metadata(
  field_id = NULL,
  query = NULL,
  ukb_data_dict = NULL,
  dataset = NULL,
  fields_df = NULL,
  entity = "participant"
)

Arguments

Value

A data.frame with one row per UKB field and standardized metadata columns. When RAP field metadata is available, the result also includes the matching RAP column names and the number of approved RAP columns per field.

Query the built-in medication code catalog

Description

Returns a medication code catalog containing UKBAnalytica curated medication definitions and UK Biobank official coding 4 entries for field 20003.

Usage

get_medication_catalog(medication = NULL, medication_class = NULL)

Arguments

Value

A data.frame.

Examples

metformin <- get_medication_catalog("metformin")
head(metformin)

Get Pomegranate-derived disease definitions

Description

Converts the Pomegranate-derived rows in the disease catalog into UKBAnalytica disease definition objects. Only code systems currently supported by the package parsers are used by default; GP and medication rows remain available through get_disease_catalog().

Usage

get_pomegranate_diseases(disease = NULL, supported_only = TRUE)

Arguments

Value

A named list of disease definition objects.

Examples

pom <- get_pomegranate_diseases("asthma")
names(pom)

Get the Pomegranate source manifest

Description

Returns source provenance for the built-in Pomegranate resources, including the GitHub YAML commit used for the canonical disease catalog and the portal CSV retained for audit.

Usage

get_pomegranate_source_manifest()

Value

A data.frame.

Examples

get_pomegranate_source_manifest()

Get Predefined Disease Definitions

Description

Returns a list of commonly used cardiovascular and metabolic disease definitions with validated ICD-10, ICD-9, and self-report code mappings.

Usage

get_predefined_diseases(
  source = c("curated", "pomegranate", "both"),
  merge_type = c("intersection", "union"),
  disease = NULL,
  supported_only = TRUE
)

Arguments

Details

Included diseases:

AA

Aortic Aneurysm (I71, 441)

TAA

Thoracic Aortic Aneurysm

AAA

Abdominal Aortic Aneurysm

CVD

Cardiovascular Disease

MI

Myocardial Infarction

HF

Heart Failure

Stroke

Stroke (ischemic and hemorrhagic)

Hypertension

Essential and secondary hypertension

Diabetes

Diabetes Mellitus (all types)

T1DM

Type 1 Diabetes Mellitus

T2DM

Type 2 Diabetes Mellitus

Vascular_Disease

Peripheral vascular disease

Arrhythmia

Broad cardiac arrhythmia endpoint including OPCS4 procedures

Atrial_Fibrillation

Atrial arrhythmia / atrial fibrillation-flutter

Ventricular_Arrhythmia

Ventricular arrhythmia endpoint

AV_Block

Atrioventricular conduction block

Intraventricular_Block

Intraventricular conduction block

SVT

Supraventricular tachycardia

Lung_Cancer

Lung cancer using ICD-10/death and cancer registry

Additional chronic diseases

Common respiratory, renal, gastrointestinal, neurologic, psychiatric, eye, skin, musculoskeletal, and cancer endpoints used in UKB epidemiology workflows

Value

A named list of disease definition objects.

Get predefined UK Biobank medication definitions

Description

Returns curated field-20003 medication code sets for common self-reported treatment groups. These definitions are designed for baseline covariate derivation and sensitivity analyses, and are separate from disease endpoint definitions returned by get_predefined_diseases().

Usage

get_predefined_medications()

Value

A named list of medication definition objects.

Examples

meds <- get_predefined_medications()
names(meds)

Retrieve a STRING PPI network for proteomics hits

Description

Convert protein identifiers to gene symbols and retrieve a protein-protein interaction network from STRING via clusterProfiler::getPPI().

Usage

get_protein_ppi(
  proteins,
  protein_col = NULL,
  from_type = "SYMBOL",
  mapping_table = NULL,
  mapping_protein_col = "protein",
  mapping_symbol_col = "gene_symbol",
  organism_db = "org.Hs.eg.db",
  taxID = 9606,
  required_score = NULL,
  network_type = "functional",
  add_nodes = 0,
  show_query_node_labels = 0,
  output = c("igraph", "data.frame")
)

Arguments

Value

A list with components source, gene_symbols, mapping, and ppi.

Get column names of the synthetic UK Biobank-style demo dataset

Description

Returns the column names generated by ukb_demo(). This is useful for documentation examples that need RAP-style toy column names.

Usage

get_ukb_demo_colnames()

Value

A character vector of original demo-data column names.

Examples

get_ukb_demo_colnames()

Get information about available variables

Description

Returns a data.frame describing all predefined variables available for preprocessing.

Usage

get_variable_info(category = "all")

Arguments

Value

A data.frame with variable information

Get one curated UK Biobank variable set

Description

Get one curated UK Biobank variable set

Usage

get_variable_set(set, output = c("data.frame", "field_id", "ukb_col"))

Arguments

Value

A data.frame or character/integer vector.

Examples

get_variable_set("clinical_core")
get_variable_set("air_pollution", output = "field_id")

Curated UK Biobank variable sets for extraction

Description

Returns curated UKB field groups for common analysis domains. These sets are intended for field discovery and RAP extraction, not for automatic preprocessing. Use preprocess_baseline() only for variables documented by get_variable_info().

Usage

get_variable_sets(set = NULL, category = NULL)

Arguments

Value

A data.frame with one row per curated variable.

Examples

vars <- get_variable_sets("air_pollution")
unique(vars$field_id)

Load the Pomegranate portal coding evidence table

Description

Loads a long-form Pomegranate portal extraction from a user-supplied local CSV or CSV.GZ file for audit and traceability. The canonical Pomegranate disease catalog used by get_disease_catalog(source = "pomegranate") is built into the package from the public GitHub YAML algorithms; the portal audit table is not required for endpoint construction and is not shipped in the CRAN build.

Usage

load_pomegranate_portal_coding(path = NULL)

Arguments

Value

A data.frame.

Load UK Biobank field 20003 medication coding

Description

Loads the UK Biobank coding 4 table used by field 20003 (treatment/medication code). This table is included as a lightweight reference so users can inspect the meaning of medication codes used by get_predefined_medications().

Usage

load_ukb_medication_coding(path = NULL)

Arguments

Value

A data.frame with columns coding and meaning.

Examples

coding4 <- load_ukb_medication_coding()
head(coding4)

Load the bundled UK Biobank non-ratio metabolite panel

Description

Read the metabolite metadata table bundled in inst/extdata. The current file contains UK Biobank Nightingale non-ratio metabolite names, field IDs, and RAP-style column names. It is mainly intended as a helper for examples, tests, and metabolite-name checking.

Usage

load_ukb_metabolite_panel(file = NULL, file_encoding = "UTF-16LE")

Arguments

Value

A data.frame with columns such as Description, UKB_ID, and meta_ID.

Examples

panel <- load_ukb_metabolite_panel()
head(panel)

Propensity Score Matching

Description

Perform propensity score matching using nearest neighbor or optimal matching.

Usage

match_propensity(
  data,
  ps_col = "ps",
  treatment,
  ratio = 1,
  caliper = 0.2,
  method = c("nearest", "optimal"),
  replace = FALSE,
  exact_match = NULL
)

Arguments

Value

A data.table with matched data, including:

match_id

Matched pair identifier

match_distance

Distance between matched pairs

Map metabolite names to MetaboAnalyst-compatible names

Description

Convert common UK Biobank Nightingale metabolite labels to names that are more likely to be recognized by MetaboAnalystR name cross-referencing. Users can provide a custom mapping table to override or extend the built-in map.

Usage

metabolite_to_metaboanalyst_name(
  metabolites,
  mapping_table = NULL,
  mapping_metabolite_col = "metabolite",
  mapping_name_col = "metaboanalyst_name",
  drop_unmapped = FALSE
)

Arguments

Value

A data.frame with metabolite, metaboanalyst_name, and mapping_source.

Examples

metabolite_to_metaboanalyst_name(c("Acetate", "Alanine", "LDL Cholesterol"))

Multiple Imputation Result Pooling

Description

Functions for combining results from analyses performed on multiply imputed datasets using Rubin's Rules. Supports various regression models including linear, logistic, Poisson, Cox, and negative binomial regression.

Machine Learning Model Evaluation

Description

Functions for evaluating and visualizing ML model performance.

Machine Learning Module for UK Biobank Data Analysis

Description

Unified machine learning interface for UK Biobank data analysis. Supports classification, regression, and provides consistent API across different ML algorithms.

SHAP Explanations for Machine Learning Models

Description

Compute and visualize SHAP (SHapley Additive exPlanations) values for interpreting ML model predictions.

Survival Machine Learning Module

Description

Machine learning models for survival analysis including random survival forests and gradient boosting survival models.

Parse Cancer Registry Records

Description

Extracts cancer registry records from UK Biobank fields 40006, 40005, 40011, and 40012 into a standardized long-format table. Field 40006 stores cancer ICD-10 type, 40005 stores diagnosis date, 40011 stores tumour histology, and 40012 stores tumour behaviour.

Usage

parse_cancer_registry(dt)

Arguments

Value

A data.table with columns: eid, cancer_icd10_code, diag_date, cancer_histology, cancer_behaviour, and source.

Parse Death Registry Records

Description

Extracts death registry data from UK Biobank linked mortality records. Parses both primary (p40001) and contributing (p40002) causes of death along with death dates (p40000). Caution: Death records only contain ICD-10 codes.

Usage

parse_death_records(dt)

Arguments

Details

Death causes serve as definitive diagnosis confirmation. If a participant died from a specific disease, the death date becomes the diagnosis date for that condition (if not previously diagnosed).

Value

A data.table with columns:

eid

Participant identifier

death_code

ICD-10 cause of death code

death_date

Date of death

source

Data source identifier ("Death")

cause_type

"primary" or "secondary"

Parse ICD-10 Hospital Diagnosis Records

Description

Extracts ICD-10 diagnosis codes from UK Biobank hospital inpatient data. Converts the mixed-format storage (Python list string in p41270 + date array in p41280_a*) into a standardized long-format data.table.

Usage

parse_icd10_diagnoses(dt)

Arguments

Details

The function implements the Index-Match logic specified in the UKB data dictionary: the k-th element in p41270 corresponds to date column p41280_a(k-1) (0-indexed).

Processing pipeline:

1. Parse Python list string format in p41270

2. Melt p41280_a* date columns to long format

3. Join codes and dates by eid and positional index

Value

A data.table with columns:

eid

Participant identifier

icd10_code

ICD-10 diagnosis code

diag_date

Date of diagnosis

source

Data source identifier ("ICD10")

Parse ICD-9 Hospital Diagnosis Records

Description

Extracts ICD-9 diagnosis codes from UK Biobank hospital inpatient data. Converts the mixed-format storage (Python list string in p41271 + date array in p41281_a*) into a standardized long-format data.table.

Usage

parse_icd9_diagnoses(dt)

Arguments

Details

ICD-9 codes in UKB follow the format: 3-5 digits, optionally prefixed with V or E. The function handles logical NA columns that may occur when all values are missing.

Value

A data.table with columns:

eid

Participant identifier

icd9_code

ICD-9 diagnosis code

diag_date

Date of diagnosis

source

Data source identifier ("ICD9")

Parse OPCS4 Hospital Procedure Records

Description

Extracts OPCS4 operative procedure codes from UK Biobank hospital inpatient summary operations data. Supports the common export shape where p41272 stores a list-string of codes and p41282_a* stores the corresponding dates, while also tolerating expanded p41272_a* columns.

Usage

parse_opcs4_procedures(dt)

Arguments

Details

The function implements the same index-matching logic used for UKB summary diagnosis fields: the k-th procedure code in p41272 corresponds to the date stored in p41282_a(k-1) (0-indexed).

Value

A data.table with columns:

eid

Participant identifier

opcs4_code

OPCS4 procedure code

diag_date

Date of first recorded procedure for that code/index

source

Data source identifier ("OPCS4")

Parse Self-Reported Illness Records

Description

Extracts self-reported illness data from UK Biobank touchscreen questionnaire. Converts coded illness data (p20002_i*_a*) and interpolated year of diagnosis (p20008_i*_a*) into a standardized long-format data.table.

Usage

parse_self_reported_illnesses(dt, baseline_col = "p53_i0")

Arguments

Details

Year-to-date conversion logic:

• p20008 stores fractional years (e.g., 1983.5 = mid-1983)

• Fractional part * 12 = approximate month

• Special values (-1, -3) indicate "don't know" or "prefer not to answer"

Value

A data.table with columns:

eid

Participant identifier

sr_code

Self-report illness code

diag_date

Approximate date of diagnosis

source

Data source identifier ("Self-report")

instance

Assessment instance (0, 1, 2, 3)

array_idx

Array index within instance

Plot a UKB ML Flow Object

Description

Plot a UKB ML Flow Object

Usage

## S3 method for class 'ukb_ml_flow'
plot(x, type = c("roc", "shap_beeswarm"), ...)

Arguments

Value

A ggplot2 object.

Plot a UKB ML Flow Comparison Object

Description

Plot a UKB ML Flow Comparison Object

Usage

## S3 method for class 'ukb_ml_flow_compare'
plot(x, type = c("roc"), ...)

Arguments

Value

A ggplot2 object.

Plot Covariate Balance (Love Plot)

Description

Create a Love plot comparing standardized mean differences before and after matching/weighting.

Usage

plot_balance(
  balance_before,
  balance_after,
  threshold = 0.1,
  title = "Covariate Balance",
  xlab = "Standardized Mean Difference"
)

Arguments

Value

A ggplot2 object.

Plot Calibration Curve

Description

Create a calibration plot comparing predicted probabilities to observed outcomes.

Usage

plot_calibration(
  data,
  predicted,
  observed,
  n_bins = 10,
  smooth = TRUE,
  conf_int = TRUE
)

Arguments

Value

A ggplot2 object.

Visualize correlation matrix as a heatmap

Description

Create an annotated heatmap of a correlation matrix with customizable appearance. This helps identify patterns, multicollinearity, and variable relationships visually.

Usage

plot_correlation(
  corr_matrix,
  title = "Correlation Matrix",
  show_values = TRUE,
  digits = 2,
  text_size = 3,
  color_low = "#3B4CC0",
  color_mid = "white",
  color_high = "#B40426",
  upper_triangle = FALSE
)

Arguments

Value

A ggplot2 object. Can be further customized with ggplot2 functions.

Plot training-validation Cox log(HR) concordance

Description

Plot training-validation Cox log(HR) concordance

Usage

plot_cox_loghr_correlation(
  comparison,
  train_loghr_col = "train_logHR",
  validation_loghr_col = "validation_logHR",
  highlight_col = "train_significant_bonferroni",
  highlight_label = "Train Bonferroni significant"
)

Arguments

Value

A ggplot object.

Plot sensitivity-analysis Cox log(HR) concordance

Description

Plot sensitivity-analysis Cox log(HR) concordance

Usage

plot_cox_sensitivity_correlation(
  comparison,
  sensitivity_col = "sensitivity",
  main_loghr_col = "main_logHR",
  sensitivity_loghr_col = "sensitivity_logHR",
  highlight_col = "main_significant_bonferroni",
  highlight_label = "Main Bonferroni significant",
  nrow = NULL,
  ncol = NULL
)

Arguments

Value

A ggplot object.

Plot enrichment results as a lollipop chart via TCMDATA

Description

A thin wrapper around TCMDATA::gglollipop() for enrichment results. This function accepts either a raw enrichResult object or a list returned by one of the proteomics ORA helpers in this package.

Usage

plot_enrichment_lollipop(x, ...)

Arguments

Value

A ggplot2 object.

Plot Forest Plot for Subgroup Analysis

Description

Create a forest plot to visualize subgroup analysis results with effect estimates and confidence intervals.

Usage

plot_forest(
  results,
  estimate_col = "estimate",
  lower_col = "lower95",
  upper_col = "upper95",
  label_col = "subgroup",
  pvalue_col = "pvalue",
  p_interaction_col = "p_interaction",
  null_value = 1,
  log_scale = TRUE,
  colors = NULL,
  title = "Subgroup Analysis",
  xlab = "Hazard Ratio (95% CI)",
  show_n = TRUE,
  show_events = TRUE
)

Arguments

Value

A ggplot2 object.

Plot GO ORA results as a bar chart via TCMDATA

Description

A thin wrapper around TCMDATA::go_barplot() for GO enrichment results. This function accepts either a raw enrichResult object or a list returned by run_protein_ora().

Usage

plot_go_ora_bar(x, ...)

Arguments

Value

A ggplot2 object.

Plot a publication-style heatmap

Description

Draw a compact heatmap from long-format data. The function uses string column names and .data pronouns internally, which makes it suitable for scripted package workflows and CRAN checks.

Usage

plot_heatmap(
  data,
  x,
  y,
  fill,
  label = NULL,
  show_values = FALSE,
  low = "#2F6FA3",
  mid = "#F7F7F7",
  high = "#C74732",
  midpoint = 0,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  fill_lab = NULL,
  base_size = 7
)

Arguments

Value

A ggplot object.

Plot Kaplan-Meier Survival Curve

Description

Create a Kaplan-Meier survival curve with optional risk table and log-rank p-value.

Usage

plot_km_curve(
  data,
  time_col,
  status_col,
  group_col = NULL,
  conf_int = TRUE,
  risk_table = TRUE,
  censor_marks = TRUE,
  palette = "jco",
  title = NULL,
  xlab = "Time (years)",
  ylab = "Survival Probability",
  legend_title = "Group",
  median_line = TRUE,
  pvalue = TRUE,
  xlim = NULL,
  break_time = NULL
)

Arguments

Value

A ggplot2 object (or a list with plot and risk table if risk_table = TRUE).

Plot Mediation Analysis Results

Description

Create visualizations for mediation analysis results, including path diagrams, effect bar charts, and decomposition plots.

Usage

plot_mediation(
  mediation_result,
  type = c("effects", "path", "decomposition"),
  show_ci = TRUE,
  show_pvalue = TRUE,
  exponentiate = FALSE,
  title = NULL,
  colors = NULL
)

Arguments

Value

A ggplot2 object.

Plot Forest Plot for Multiple Mediator Analysis

Description

Create a forest plot to visualize results from multiple mediator analysis.

Usage

plot_mediation_forest(
  multi_mediation_result,
  effect_type = c("tnie", "pnde", "te", "pm"),
  exponentiate = FALSE,
  null_value = 0,
  title = "Mediation Analysis: Multiple Mediators"
)

Arguments

Value

A ggplot2 object.

Plot metabolite ORA results as a bar plot

Description

Plot metabolite ORA results as a bar plot

Usage

plot_metabolite_ora_barplot(
  x,
  top_n = 15,
  p_col = "pvalue",
  pathway_col = "pathway",
  fill_color = "#2F6FA3"
)

Arguments

Value

A ggplot object.

Plot metabolite ORA results as a dot plot

Description

Plot metabolite ORA results as a dot plot

Usage

plot_metabolite_ora_dotplot(
  x,
  top_n = 15,
  p_col = "pvalue",
  size_col = "hits",
  pathway_col = "pathway",
  color_low = "#2F6FA3",
  color_high = "#C74732"
)

Arguments

Value

A ggplot object.

Plot Multiple Imputation Diagnostics

Description

Creates diagnostic plots for multiple imputation results, including fraction of missing information (FMI), variance ratios, and degrees of freedom.

Usage

plot_mi_diagnostics(
  mi_result,
  type = c("fmi", "variance_ratio", "df"),
  title = NULL
)

Arguments

Value

A ggplot2 object.

Plot Multiple Imputation Pooled Results

Description

Creates a forest plot for pooled estimates from multiple imputation analysis.

Usage

plot_mi_pooled(
  mi_result,
  terms = NULL,
  exponentiate = NULL,
  null_value = NULL,
  title = "Pooled Estimates (Multiple Imputation)",
  colors = NULL,
  show_fmi = TRUE
)

Arguments

Value

A ggplot2 object.

Plot Calibration Curve

Description

Create calibration curve plot showing predicted vs observed probabilities.

Usage

plot_ml_calibration(object, title = "Calibration Curve", ...)

Arguments

Value

A ggplot2 object

Plot Model Comparison

Description

Create comparison plot for multiple ML models.

Usage

plot_ml_compare(
  object,
  metric = NULL,
  type = c("bar", "dot"),
  title = "Model Comparison",
  ...
)

Arguments

Value

A ggplot2 object

Plot Confusion Matrix

Description

Create heatmap visualization of confusion matrix.

Usage

plot_ml_confusion(
  object,
  normalize = TRUE,
  colors = c("white", "#E34A33"),
  title = "Confusion Matrix",
  ...
)

Arguments

Value

A ggplot2 object

Plot Decision Curve Analysis

Description

Create a Decision Curve Analysis plot showing net benefit of the model compared to treat-all and treat-none strategies.

Usage

plot_ml_dca(object, title = "Decision Curve Analysis", ...)

Arguments

Value

A ggplot2 object

Plot Gain Curve

Description

Create a Gain curve plot comparing model targeting against random selection.

Usage

plot_ml_gain(object, title = "Gain Curve", ...)

Arguments

Value

A ggplot2 object

Plot Variable Importance

Description

Create a bar plot of variable importance from a trained ML model.

Usage

plot_ml_importance(
  object,
  n_features = 20,
  type = c("bar", "dot"),
  color = "#3182BD",
  title = "Variable Importance",
  ...
)

Arguments

Value

A ggplot2 object

Plot KS Curve

Description

Create a KS (Kolmogorov-Smirnov) curve plot showing TPR, FPR, and their difference (KS statistic) across thresholds.

Usage

plot_ml_ks(object, title = "KS Curve", ...)

Arguments

Value

A ggplot2 object

Plot Lift Curve

Description

Create a Lift curve plot showing the ratio of model vs random targeting.

Usage

plot_ml_lift(object, title = "Lift Curve", ...)

Arguments

Value

A ggplot2 object

Plot PR Curve

Description

Create a Precision-Recall curve plot with AUPRC annotation.

Usage

plot_ml_pr(object, title = "PR Curve", ...)

Arguments

Value

A ggplot2 object

Plot ROC Curves

Description

Create ROC curve plot for one or more ML models.

Usage

plot_ml_roc(object, ci_alpha = 0.2, title = "ROC Curve", ...)

Arguments

Value

A ggplot2 object

Plot One or More ROC Curves from Tidy ROC Data

Description

Creates a publication-ready ROC curve plot from one or more data frames returned by ukb_ml_roc_data. AUC and 95% confidence interval values are included in the legend when available.

Usage

plot_ml_roc_compare(
  roc_data,
  colors = NULL,
  show_auc = TRUE,
  title = NULL,
  xlab = "1 - Specificity",
  ylab = "Sensitivity",
  legend_position = "bottom",
  base_size = 7,
  ...
)

Arguments

Value

A ggplot2 object.

Plot a participant flow table

Description

Plot a participant flow table

Usage

plot_participant_flow(
  flow,
  show_removed = TRUE,
  show_events = TRUE,
  fill = "#2C7FB8"
)

Arguments

Value

A ggplot object.

Examples

dat <- data.frame(eid = 1:5, age = c(50, 60, NA, 55, 70), status = c(0, 1, 0, 1, 0))
flow <- ukb_participant_flow(dat, list("Complete age" = "age"), outcome_col = "status")
plot_participant_flow(flow)

Plot Propensity Score Distribution

Description

Visualize the distribution of propensity scores by treatment group.

Usage

plot_ps_distribution(
  data,
  ps_col = "ps",
  treatment,
  type = c("histogram", "density", "mirror"),
  matched = FALSE,
  match_col = NULL
)

Arguments

Value

A ggplot2 object.

Plot a restricted cubic spline exposure-response curve

Description

Produces a publication-ready ggplot2 figure from a ukb_rcs object returned by run_rcs. The main panel shows the estimated effect curve with a 95\ (histogram, density, or rug) is drawn behind the curve to show exposure density. P values and the knot count are annotated by default.

Usage

plot_rcs(x, ...)

## S3 method for class 'ukb_rcs'
plot(x, ...)

## S3 method for class 'ukb_rcs'
plot_rcs(
  x,
  show_distribution = TRUE,
  distribution = c("histogram", "density", "rug"),
  show_ref = TRUE,
  show_p = TRUE,
  show_knots = TRUE,
  curve_color = "#2166AC",
  dist_color = "#AECDE8",
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  ...
)

Arguments

Value

A ggplot2 object.

Plot a volcano-style regression summary

Description

Create a volcano-style plot from regression summary results such as runmulti_cox() or runmulti_logit(). The x-axis shows the supplied effect estimate column (for example HR or OR), and the y-axis shows -log10(P). Points can be highlighted by an adjusted p-value column, while labels are selected from the largest and smallest highlighted effects.

Usage

plot_regression_volcano(
  data,
  effect_col = NULL,
  p_col = "pvalue",
  adjusted_p_col = NULL,
  label_col = NULL,
  significance_cutoff = 0.05,
  top_n_label_each = 5,
  null_effect = 1,
  x_lab = NULL,
  y_lab = NULL,
  x_limits = NULL,
  y_limits = NULL,
  point_size = 1.05,
  label_size = 2,
  colors = c(neutral = "#D8D8D8", lower = "#2F6FA3", higher = "#C74732"),
  show_cutoff = TRUE
)

Arguments

Value

A ggplot2 object with attributes plot_data and label_data.

Plot a publication-style scatter plot

Description

Draw a scatter plot with optional color grouping, linear smooth, and reference line. This is intended for compact association or validation panels.

Usage

plot_scatter(
  data,
  x,
  y,
  color = NULL,
  palette = NULL,
  add_smooth = TRUE,
  add_identity = FALSE,
  alpha = 0.72,
  point_size = 1.2,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  base_size = 7
)

Arguments

Value

A ggplot object.

Plot SHAP Beeswarm Summary

Description

Creates a SHAP beeswarm plot directly from a ukb_shap object. The plot displays the top features ranked by mean absolute SHAP value, with point color representing the normalized feature value.

Usage

plot_shap_beeswarm(
  object,
  max_features = 20,
  label_map = NULL,
  feature_col = "feature",
  label_col = "label",
  colors = c("#1E88E5", "#7B3294", "#FF0051"),
  point_size = 0.58,
  alpha = 0.62,
  jitter_height = 0.18,
  seed = 20260509,
  title = NULL,
  xlab = "SHAP value",
  legend_title = "Feature value",
  base_size = 7,
  return_data = FALSE,
  ...
)

Arguments

Value

A ggplot2 object, or a list with plot data when return_data = TRUE.

Plot SHAP Dependence

Description

Create SHAP dependence plot showing the relationship between a feature's value and its SHAP value.

Usage

plot_shap_dependence(
  object,
  feature,
  color_feature = NULL,
  alpha = 0.5,
  smooth = TRUE,
  title = NULL,
  ...
)

Arguments

Value

A ggplot2 object

Plot SHAP Force (Waterfall)

Description

Create a waterfall plot showing feature contributions for a single prediction.

Usage

plot_shap_force(object, row_id = 1, max_features = 10, title = NULL, ...)

Arguments

Value

A ggplot2 object

Plot SHAP Summary

Description

Create SHAP summary plot (beeswarm or bar) for feature importance.

Usage

plot_shap_summary(
  object,
  max_features = 20,
  type = c("beeswarm", "bar"),
  color_palette = "viridis",
  title = "SHAP Summary",
  ...
)

Arguments

Value

A ggplot2 object

Plot a publication-style stacked bar chart

Description

Summarize observations by x and fill, then draw either proportional or count-based stacked bars.

Usage

plot_stacked_bar(
  data,
  x,
  fill,
  weight = NULL,
  position = c("fill", "stack"),
  palette = NULL,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  legend_title = NULL,
  base_size = 7
)

Arguments

Value

A ggplot object.

Plot top positive and inverse Cox associations

Description

Plot top positive and inverse Cox associations

Usage

plot_top_hr_bars(
  top_results,
  facet_col = "dataset",
  hr_col = "HR",
  lower_col = "lower95",
  upper_col = "upper95",
  label_col = "label"
)

Arguments

Value

A ggplot object.

Plot a publication-style violin plot

Description

Draw grouped distributions using violin layers with optional boxplot overlay.

Usage

plot_violin(
  data,
  x,
  y,
  fill = NULL,
  palette = NULL,
  add_boxplot = TRUE,
  add_points = FALSE,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  base_size = 7
)

Arguments

Value

A ggplot object.

Pool Custom Estimates from Multiple Imputations

Description

Combines custom parameter estimates (not limited to regression coefficients) from multiply imputed datasets using Rubin's Rules.

Usage

pool_custom_estimates(
  estimates,
  variances,
  df.complete = Inf,
  conf.level = 0.95,
  labels = NULL
)

Arguments

Value

An object of class mi_pooled_result.

Pool Results from Multiple Imputation Models

Description

Combines results of regression analyses performed on multiply imputed datasets using Rubin's Rules via the mitools package.

Usage

pool_mi_models(
  models = NULL,
  datasets = NULL,
  formula = NULL,
  model_type = c("lm", "logistic", "poisson", "cox", "negbin"),
  family = NULL,
  df.complete = Inf,
  conf.level = 0.95,
  exponentiate = NULL
)

Arguments

Value

An object of class mi_pooled_result containing:

pooled

Data frame with pooled estimates, standard errors, CIs, p-values, and FMI

mi_result

The raw MIresult object from mitools

n_imputations

Number of imputed datasets

model_type

The model type used

formula

The model formula

exponentiated

Whether estimates are exponentiated

call

The function call

Preprocess UKB baseline variables

Description

A unified function to preprocess UKB baseline characteristics with automatic field mapping and standardized transformations.

Usage

preprocess_baseline(
  df,
  variables,
  custom_mapping = NULL,
  missing_action = c("keep", "drop"),
  invalid_codes = c(-1, -3)
)

Arguments

Value

A data.table with original data plus processed variable columns

Print Method for Mediation Results

Description

Print mediation analysis results.

Usage

## S3 method for class 'mediation_result'
print(x, ...)

Arguments

Value

Invisibly returns x, the original mediation result object.

Convert protein identifiers to gene symbols

Description

Convert a vector of protein identifiers into HGNC gene symbols for downstream enrichment analysis. When a custom mapping table is supplied, it is used first. Remaining unmatched identifiers can then be mapped with clusterProfiler::bitr(). Inputs in UK Biobank Olink coding 143 format, such as "IL6;Interleukin-6", and RAP-exported Olink column names such as "olink_instance_0.eno2" are parsed automatically. Multi-target Olink symbols such as "IL12A_IL12B" are expanded into one row per gene symbol.

Usage

protein_to_gene_symbol(
  proteins,
  protein_col = NULL,
  from_type = "SYMBOL",
  mapping_table = NULL,
  mapping_protein_col = "protein",
  mapping_symbol_col = "gene_symbol",
  organism_db = "org.Hs.eg.db",
  drop_unmapped = TRUE
)

Arguments

Value

A data.frame with columns protein, gene_symbol, and mapping_source.

Rank nodes in a PPI network by integrated centrality

Description

A thin wrapper around TCMDATA::rank_ppi_nodes().

Usage

rank_protein_ppi_nodes(
  ppi,
  metrics = c("degree", "betweenness", "closeness", "eccentricity", "radiality",
    "Stress", "MCC", "MNC", "DMNC", "BN", "EPC"),
  weights = NULL,
  use_weight = TRUE,
  na_rm = TRUE
)

Arguments

Value

A list with components graph and table.

RAP Phenotype Extraction Helpers

Description

R-native wrappers around DNAnexus ⁠dx extract_dataset⁠ and the RAP table-exporter app. These functions are intended for use inside approved UK Biobank RAP sessions or RAP-controlled execution environments.

Extract RAP Phenotype Data Synchronously

Description

Uses dx extract_dataset --fields-file and reads the RAP-generated result back into R within the active RAP session. This is intended for small to medium extractions. For large phenotype pulls, use rap_submit_extract().

Usage

rap_extract_pheno(
  field_id = NULL,
  field_names = NULL,
  variables = NULL,
  dataset = NULL,
  output = NULL,
  read = TRUE,
  strip_entity_prefix = FALSE,
  dry_run = FALSE,
  timeout = 300,
  ...
)

Arguments

Value

A data.table when read = TRUE; otherwise the output CSV path. In dry-run mode, returns a rap_extract_plan.

Find the RAP Dataset File in the Current Project

Description

Find the RAP Dataset File in the Current Project

Usage

rap_find_dataset(refresh = FALSE, timeout = 30)

Arguments

Value

A character scalar naming the detected .dataset file.

List Approved RAP Dataset Fields

Description

List Approved RAP Dataset Fields

Usage

rap_list_fields(
  dataset = NULL,
  pattern = NULL,
  entity = "participant",
  refresh = FALSE,
  timeout = 120
)

Arguments

Value

A data.frame with columns field_name and title.

Plan a RAP Phenotype Extraction

Description

Plan a RAP Phenotype Extraction

Usage

rap_plan_extract(
  field_id = NULL,
  field_names = NULL,
  variables = NULL,
  dataset = NULL,
  fields_df = NULL,
  entity = "participant",
  include_eid = TRUE,
  table_exporter = FALSE,
  manifest = NULL
)

Arguments

Value

A list containing extraction field names, matched requests, unmatched requests, dataset, entity, and column counts.

Submit a RAP Table-Exporter Phenotype Extraction Job

Description

Submits an asynchronous RAP table-exporter job. This is the preferred interface for large extraction jobs because the work runs on RAP rather than inside the current R session.

Usage

rap_submit_extract(
  field_id = NULL,
  field_names = NULL,
  variables = NULL,
  dataset = NULL,
  file = NULL,
  instance_type = NULL,
  priority = c("low", "high"),
  dry_run = FALSE,
  manifest = NULL,
  ...
)

Arguments

Value

A list with class rap_extract_job containing job metadata. In dry-run mode, returns a rap_extract_plan.

Regression Extension Functions for UKBAnalytica

Description

Additional regression helpers for common UK Biobank workflows, including Cox proportional hazards diagnostics, grouped-exposure trend tests, Fine-Gray competing-risk models, and lagged Cox sensitivity analyses.

Calculate correlation between variables

Description

Before the formal regression analysis, it can be useful to check the correlation between variables. This function calculates the correlation matrix for a set of specified variables, which can help identify potential multicollinearity issues or inform variable selection.

Usage

run_correlation(df, vars, method = "pearson", threshold = 0.7)

Arguments

Value

A correlation matrix of the specified variables.

Multiple imputation and merge back to full data

Description

Run multiple imputation with the CRAN package mice on a subset of variables, then merge the imputed columns back to the original dataset by an ID column.

Usage

run_imputation(
  data,
  id_col = "eid",
  vars,
  factor_vars = NULL,
  method = "pmm",
  m = 5,
  maxit = 10,
  seed = 1234,
  print = TRUE,
  additional_data = NULL,
  additional_join = c("inner", "left")
)

Arguments

Details

This function is designed for workflows where you want to keep a set of "static" columns (exposures, outcomes, follow-up time, etc.) untouched while imputing a selected set of covariates.

The function:

1. Subsets the input data to the requested variables.

2. Runs mice().

3. Creates m completed datasets and merges imputed columns back.

4. Optionally merges additional datasets (e.g., omics) by ID.

Factor handling: for variables listed in factor_vars, the function will coerce them to factors before imputation. All other variables in vars are coerced to numeric.

Value

A list with:

• imp: the mice mids object

• data_list: a list of length m containing completed and merged datasets

References

https://github.com/amices/mice

Run Causal Mediation Analysis

Description

Perform regression-based causal mediation analysis using the regmedint package. Supports linear, logistic, and Cox proportional hazards models for the outcome, and linear or logistic models for the mediator.

Usage

run_mediation(
  data,
  exposure,
  mediator,
  outcome,
  covariates = NULL,
  exposure_levels = c(0, 1),
  mediator_value = 0,
  covariate_values = NULL,
  mediator_type = c("continuous", "binary"),
  outcome_type = c("linear", "logistic", "cox"),
  endpoint = NULL,
  interaction = TRUE,
  boot = FALSE,
  boot_n = 1000,
  conf_level = 0.95
)

Arguments

Details

This function wraps the regmedint package to provide a user-friendly interface for causal mediation analysis. It implements the methods described in Valeri & VanderWeele (2013, 2015).

Effect definitions:

• cde: Controlled Direct Effect - effect of exposure with mediator fixed

• pnde: Pure Natural Direct Effect - direct effect (traditional NDE)

• tnie: Total Natural Indirect Effect - indirect effect (traditional NIE)

• tnde: Total Natural Direct Effect

• pnie: Pure Natural Indirect Effect

• te: Total Effect = NDE + NIE

• pm: Proportion Mediated = NIE / TE

Value

An object of class "mediation_result" containing:

effects

data.frame with effect estimates, SE, CI, and p-values

mediator_model

Fitted mediator model object

outcome_model

Fitted outcome model object

regmedint_obj

Original regmedint object (if available)

call

The matched call

params

List of analysis parameters

References

Valeri L, VanderWeele TJ. Mediation analysis allowing for exposure-mediator interactions and causal interpretation. Psychological Methods. 2013;18(2):137-150.

Run metabolite over-representation analysis

Description

Run ORA for a metabolite list. The recommended first backend is backend = "custom", where users provide a two-column metabolite pathway library. A backend = "metaboanalyst" interface is also provided for users who have installed MetaboAnalystR and want to use its metabolite-set libraries, such as "smpdb_pathway".

Usage

run_metabolite_ora(
  metabolites,
  pathway_db = NULL,
  universe = NULL,
  backend = c("custom", "metaboanalyst"),
  id_type = "name",
  library = "smpdb_pathway",
  mapping_table = NULL,
  pathway_col = "pathway",
  metabolite_col = "metabolite",
  min_metabolites = 3,
  p_adjust_method = "BH",
  run_subprocess = TRUE
)

Arguments

Value

A list of class ukb_metabolite_ora with components input, mapping, matched, unmatched, ora_result, backend, and library.

Examples

panel <- load_ukb_metabolite_panel()
hits <- c("Alanine", "Glutamine", "Glycine", "Lactate", "Pyruvate")
pathway_db <- data.frame(
  pathway = c(rep("Amino acid metabolism", 3), rep("Energy metabolism", 2)),
  metabolite = c("L-Alanine", "L-Glutamine", "Glycine", "Lactic acid", "Pyruvic acid")
)
run_metabolite_ora(hits, pathway_db = pathway_db, backend = "custom")

Run Multiple Mediator Analysis

Description

Perform mediation analysis for multiple potential mediators, testing each one separately.

Usage

run_multi_mediator(
  data,
  exposure,
  mediators,
  outcome,
  covariates = NULL,
  mediator_type = "continuous",
  outcome_type = "linear",
  endpoint = NULL,
  ...
)

Arguments

Value

A data.frame with mediation results for each mediator, including:

mediator

Mediator variable name

tnie

Total natural indirect effect estimate

tnie_se

Standard error of TNIE

tnie_p

P-value for TNIE

pnde

Pure natural direct effect estimate

te

Total effect estimate

pm

Proportion mediated

pm_se

Standard error of proportion mediated

Run Multiple Subgroup Analyses

Description

Perform subgroup analyses across multiple subgroup variables.

Usage

run_multi_subgroup(
  data,
  exposure,
  outcome = NULL,
  subgroup_vars,
  covariates = NULL,
  model_type = c("cox", "logistic", "linear", "glm", "negbin"),
  family = "poisson",
  endpoint = NULL
)

Arguments

Value

A data.frame with results from all subgroup analyses combined.

Run KEGG ORA enrichment for proteomics hits

Description

Convert protein identifiers to gene symbols, then to Entrez IDs, and run over-representation analysis (ORA) with clusterProfiler::enrichKEGG().

Usage

run_protein_kegg_ora(
  proteins,
  protein_col = NULL,
  from_type = "SYMBOL",
  mapping_table = NULL,
  mapping_protein_col = "protein",
  mapping_symbol_col = "gene_symbol",
  universe = NULL,
  organism_db = "org.Hs.eg.db",
  organism = "hsa",
  pvalueCutoff = 0.05,
  qvalueCutoff = 0.2,
  pAdjustMethod = "BH",
  minGSSize = 10,
  maxGSSize = 500,
  readable = TRUE,
  use_internal_data = FALSE
)

Arguments

Value

A list with components gene_symbols, entrez_ids, mapping, universe_symbols, universe_entrez_ids, and ora_result.

Run GO ORA enrichment for proteomics hits

Description

Convert protein identifiers to gene symbols and run over-representation analysis (ORA) with clusterProfiler::enrichGO(). This is the GO-specific interface for proteomics hits extracted from UK Biobank RAP Olink data.

Usage

run_protein_ora(
  proteins,
  protein_col = NULL,
  from_type = "SYMBOL",
  mapping_table = NULL,
  mapping_protein_col = "protein",
  mapping_symbol_col = "gene_symbol",
  universe = NULL,
  organism_db = "org.Hs.eg.db",
  ont = "BP",
  pvalueCutoff = 0.05,
  qvalueCutoff = 0.2,
  pAdjustMethod = "BH",
  minGSSize = 10,
  maxGSSize = 500,
  readable = TRUE
)

Arguments

Value

A list with components gene_symbols, mapping, universe_symbols, and ora_result.

Cluster a protein-protein interaction network

Description

Unified interface for community detection in STRING-derived PPI networks. New analyses should call this function and choose the algorithm with method. Method-specific helper functions are retained internally.

Usage

run_protein_ppi_clustering(
  ppi,
  method = c("fastgreedy", "louvain", "mcode", "mcl"),
  ...
)

Arguments

Value

An igraph object with method-specific cluster attributes.

Evaluate PPI network robustness for selected protein targets

Description

Convert target protein identifiers to gene symbols and run STRING-network robustness analysis via TCMDATA::ppi_knock().

Usage

run_protein_ppi_robustness(
  ppi,
  targets,
  target_col = NULL,
  from_type = "SYMBOL",
  mapping_table = NULL,
  mapping_protein_col = "protein",
  mapping_symbol_col = "gene_symbol",
  organism_db = "org.Hs.eg.db",
  n_perm = 100L,
  weight_attr = "score",
  rewire_niter = 10L,
  seed = 42L
)

Arguments

Value

A list with components targets, mapping, and robustness.

Fit a restricted cubic spline exposure-response model

Description

Fits a restricted cubic spline (RCS) model to characterise nonlinear exposure-response relationships. Supports Cox, logistic, and linear regression. Returns prediction curves, confidence intervals, overall and nonlinear P values, and the AIC-selected knot count. The returned object is passed directly to plot_rcs() for publication-ready figures.

Usage

run_rcs(
  data,
  exposure,
  covariates = NULL,
  model_type = c("cox", "logistic", "linear"),
  endpoint = NULL,
  outcome = NULL,
  knots = NULL,
  knot_range = 3:7,
  ref = NULL,
  ref_quantile = 0.5,
  conf_level = 0.95,
  trim_quantiles = c(0.01, 0.99),
  grid_size = 200L,
  backend = c("rms", "ns")
)

Arguments

Value

An object of class c("ukb_rcs", "list") with elements:

model

The fitted model object.

model_type

Character. One of "cox", "logistic", "linear".

backend

Character. "rms" or "ns".

exposure

Character. Name of the exposure variable.

covariates

Character vector of covariate names.

endpoint

Character vector. Cox endpoint columns.

outcome

Character. Outcome column name.

knots

Integer. Number of knots used.

ref

Numeric. Reference exposure value.

n

Integer. Number of observations in the fitted model.

n_event

Integer. Number of events (Cox only, else NA).

p_overall

Numeric. Overall P value for the exposure term.

p_nonlinear

Numeric. P value for the nonlinear component.

prediction

data.frame with columns x, estimate, lower95, upper95.

distribution

data.frame with column x (untrimmed exposure values).

aic_table

data.frame with columns knots and AIC.

Run a regression model (unified interface)

Description

A unified wrapper around runmulti_cox, runmulti_lm, runmulti_logit, runmulti_glm, runmulti_negbin, and runmulti_gam. Select the model family with type.

Usage

run_regression(
  data,
  main_var,
  type = c("cox", "lm", "logit", "glm", "negbin", "gam"),
  outcome = NULL,
  endpoint = c("time", "status"),
  covariates = NULL,
  covariate_sets = NULL,
  family = NULL,
  smooth = TRUE,
  ...
)

Arguments

Value

A data.frame whose columns depend on type:

cox

variable, coef, se, z, HR, lower95, upper95, pvalue, n, n_event

lm

variable, beta, lower95, upper95, pvalue

logit

variable, OR, lower95, upper95, pvalue

glm

variable, family, link, beta, lower95, upper95, pvalue, n

negbin

variable, IRR, lower95, upper95, pvalue, theta, n

gam (smooth)

variable, edf, ref_df, F, pvalue, family, link, n

gam (linear)

variable, beta, lower95, upper95, pvalue, family, link, n

Sensitivity Analysis for Mediation

Description

Perform sensitivity analysis to assess the impact of unmeasured confounding on mediation effect estimates.

Usage

run_sensitivity_mediation(
  mediation_result,
  rho_values = seq(-0.9, 0.9, by = 0.1)
)

Arguments

Details

This function evaluates how the indirect effect would change if there were unmeasured confounding of the mediator-outcome relationship. The rho parameter represents the correlation between residuals that would be induced by an unmeasured confounder.

A robust mediation effect should remain significant across a range of plausible rho values.

Value

A data.frame with effect estimates under different rho values.

Run Subgroup Analysis

Description

Perform subgroup analysis by fitting regression models within each level of a subgroup variable and calculating interaction p-values.

Usage

run_subgroup_analysis(
  data,
  exposure,
  outcome = NULL,
  subgroup_var,
  covariates = NULL,
  model_type = c("cox", "logistic", "linear", "glm", "negbin"),
  family = "poisson",
  endpoint = NULL,
  ref_level = NULL
)

Arguments

Value

A data.frame with columns:

subgroup_var

Name of the subgroup variable

subgroup

Subgroup level

n

Sample size in subgroup

n_event

Number of events (for Cox/logistic models)

estimate

Effect estimate (HR for Cox, OR for logistic, Beta for linear)

lower95

Lower 95\% CI

upper95

Upper 95\% CI

pvalue

P-value for the exposure effect

p_interaction

P-value for interaction between exposure and subgroup

Run Weighted Analysis

Description

Fit regression models using IPTW weights with robust standard errors.

Usage

run_weighted_analysis(
  data,
  exposure,
  outcome = NULL,
  covariates = NULL,
  weight_col = "weight",
  model_type = c("cox", "logistic", "linear"),
  endpoint = NULL,
  robust_se = TRUE
)

Arguments

Value

A data.frame with effect estimates and confidence intervals.

Run Multiple Fine-Gray Competing-Risk Models

Description

Run Multiple Fine-Gray Competing-Risk Models

Usage

runmulti_competing(
  data,
  main_var,
  covariates = NULL,
  time_col,
  event_col,
  compete_col = NULL,
  event_value = 1,
  compete_value = 2,
  conf_level = 0.95,
  ...
)

Arguments

Value

A data.frame with subdistribution hazard ratios.

Run multiple Cox proportional hazards models

Description

Fit Cox proportional hazards models for each main variable separately. When covariates is NULL, univariate models are fitted. Otherwise, multivariate models adjusting for the specified covariates are fitted.

Usage

runmulti_cox(
  data,
  main_var,
  covariates = NULL,
  endpoint = c("time", "status"),
  ...
)

Arguments

Value

A data.frame with columns: variable, coef, se, z, HR, lower95, upper95, pvalue, n, and n_event.

Run Lagged Cox Sensitivity Analyses

Description

Run Lagged Cox Sensitivity Analyses

Usage

runmulti_cox_lag(
  data,
  main_var,
  covariates = NULL,
  endpoint = c("time", "status"),
  lag_years = c(0, 1, 2, 5),
  verbose = TRUE,
  ...
)

Arguments

Value

A data.frame containing lag-specific hazard-ratio estimates.

Run Multiple Cox Models with PH Diagnostics

Description

Run Multiple Cox Models with PH Diagnostics

Usage

runmulti_cox_zph(
  data,
  main_var,
  covariates = NULL,
  endpoint = c("time", "status"),
  transform = c("km", "rank", "identity"),
  alpha = 0.05,
  keep_models = FALSE,
  ...
)

Arguments

Value

A data.frame with effect estimates and PH-diagnostic columns.

Run multiple generalised additive models

Description

Fit GAMs (mgcv::gam) for each main variable separately. By default each main variable enters the model as a penalised thin-plate regression spline s(var), allowing non-linear dose-response relationships to be detected.

When smooth = TRUE (default) the returned table reports the smooth term's estimated degrees of freedom (edf), F-statistic, and p-value - useful for screening whether an association exists and whether it is non-linear (edf > 1). When smooth = FALSE the main variable enters as a parametric linear term and the output mirrors runmulti_glm (beta, Wald CI, p-value).

Usage

runmulti_gam(
  data,
  main_var,
  outcome,
  covariates = NULL,
  smooth = TRUE,
  family = "gaussian",
  k = -1,
  ...
)

Arguments

Value

When smooth = TRUE: a data.frame with columns variable, edf, ref_df, F, pvalue, family, link, n. When smooth = FALSE: variable, beta, lower95, upper95, pvalue, family, link, n.

Run multiple generalised linear models

Description

Fit GLMs for each main variable separately using any stats family. When covariates is NULL, univariate models are fitted. Otherwise, multivariate models are fitted.

Quasi-families (quasipoisson, quasibinomial) use Wald confidence intervals because profile-likelihood CIs are not available for quasi-likelihood models. All other families use profile-likelihood CIs via stats::confint.

Usage

runmulti_glm(
  data,
  main_var,
  family = "poisson",
  outcome,
  covariates = NULL,
  ...
)

Arguments

Value

A data.frame with columns: variable, family, link, beta, lower95, upper95, pvalue, n. For log- or logit-link families exp(beta) gives the ratio-scale effect (IRR, rate ratio, etc.).

Run multiple linear regression models

Description

Fit linear regression models (lm) for each main variable separately. When covariates is NULL, univariate models are fitted. Otherwise, multivariate models adjusting for the specified covariates are fitted.

Usage

runmulti_lm(data, main_var, covariates = NULL, outcome, ...)

Arguments

Value

A data.frame with columns: variable, beta, lower95, upper95, pvalue.

Run multiple logistic regression models

Description

Fit logistic regression models (glm with family = binomial) for each main variable separately. When covariates is NULL, univariate models are fitted. Otherwise, multivariate models adjusting for the specified covariates are fitted.

Usage

runmulti_logit(data, main_var, covariates = NULL, outcome, ...)

Arguments

Value

A data.frame with columns: variable, OR, lower95, upper95, pvalue.

Run multiple negative-binomial regression models

Description

Fit negative-binomial GLMs (MASS::glm.nb) for each main variable separately. This is the standard approach for overdispersed count outcomes where the Poisson variance assumption is violated.

The overdispersion parameter theta is estimated per model and reported alongside the effect estimate.

Usage

runmulti_negbin(data, main_var, outcome, covariates = NULL, ...)

Arguments

Value

A data.frame with columns: variable, IRR, lower95, upper95, pvalue, theta, n. IRR is the incidence rate ratio (exp(beta)). theta is the estimated negative-binomial dispersion parameter (larger values indicate less overdispersion).

Run Grouped-Exposure Trend Tests

Description

Run Grouped-Exposure Trend Tests

Usage

runmulti_trend(
  data,
  main_var,
  outcome = NULL,
  covariates = NULL,
  model_type = c("cox", "logistic", "linear"),
  endpoint = NULL,
  ref_level = NULL,
  score_method = c("integer", "median", "custom"),
  custom_scores = NULL,
  include_level_estimates = TRUE,
  ...
)

Arguments

Value

A data.frame containing grouped-effect estimates and a repeated p_trend column for each exposure.

Score network clusters in a PPI graph

Description

A thin wrapper around TCMDATA::add_cluster_score().

Usage

score_protein_ppi_clusters(ppi, cluster_attr = "louvain_cluster", min_size = 3)

Arguments

Value

A data.frame containing cluster scores.

Select Incident Cases by Time Since Enrollment

Description

Keep only participants with incident events and classify them as occurring within n_years or after n_years since enrollment. By default, the function uses outcome_surv_time and outcome_status generated by build_survival_dataset(). If the follow-up time column is not available, the function can compute it from enrollment and event dates.

Usage

select_incident_by_years(
  df,
  n_years = 5,
  time_col = "outcome_surv_time",
  status_col = "outcome_status",
  baseline_col = "p53_i0",
  event_date_col = "earliest_date",
  group_col = "incident_timing",
  output = c("combined", "split"),
  copy = TRUE,
  verbose = TRUE
)

Arguments

Value

If output = "combined", a filtered object with the same class as df, containing only participants with incident events. The output adds group_col. If time_col is missing but can be derived from dates, the function also adds time_col. If output = "split", a named list with within_n_years and after_n_years, each preserving the same class as df.

Examples

df <- data.frame(
  id = 1:5,
  outcome_surv_time = c(1.2, 4.9, 5.0, 8.1, 3.0),
  outcome_status = c(1, 1, 1, 1, 0)
)

result <- select_incident_by_years(df, n_years = 5)
table(result$incident_timing)

split_result <- select_incident_by_years(df, n_years = 5, output = "split")
names(split_result)

Exclude Early Events for Sensitivity Analysis

Description

Remove participants who experienced the event within the first n_years of follow-up. The returned dataset keeps the same columns and class as the input so it can be passed directly to the standard regression functions.

Usage

sensitivity_exclude_early_events(
  data,
  endpoint = c("outcome_surv_time", "outcome_status"),
  n_years,
  copy = TRUE,
  verbose = TRUE
)

Arguments