Package 'UKBAnalytica'

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

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)

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

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

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)

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

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"))

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.

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.

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.

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.

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.

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

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.

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.

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))

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)

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.

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"

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.

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)

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

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)

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"))

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.

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.

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)

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.

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.

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)

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)

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()

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.

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)

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.

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()

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

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")

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)

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.

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)

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)

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

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"))

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.

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"

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")

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")

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")

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

Description

Create calibration curve plot showing predicted vs observed probabilities.

Usage

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

Arguments

Value

A ggplot2 object

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

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

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

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

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

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

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

Description

Create a Precision-Recall curve plot with AUPRC annotation.

Usage

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

Arguments

Value

A ggplot2 object

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

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.

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)

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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.

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.

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

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

Description

Print mediation analysis results.

Usage

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

Arguments

Value

Invisibly returns x, the original mediation result object.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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
)