Package 'HealthMarkers'

Description

Computes adipose-related insulin sensitivity/resistance indices from fasting inputs. Expected input units (converted internally):

• Glucose G0 mmol/L -> mg/dL (* 18)

• Insulin I0 pmol/L -> muU/mL (/ 6)

• TG mmol/L -> mg/dL (* 88.57)

• HDL mmol/L -> mg/dL (* 38.67)

Reported indices (higher magnitude of negative "_inv" values implies worse adipose IR):

• Revised_QUICKI = 1 / (log10(I0 (muU/mL)) + log10(G0 (mg/dL)) + log10(FFA (mmol/L)))

• VAI (sex-specific; inverted as VAI_*_inv so larger negative = worse)

• TG_HDL_C_inv = -(TG/HDL) in mg/dL

• TyG_inv = -ln(TG (mg/dL) * G0 (mg/dL) / 2)

• LAP (sex-specific; inverted)

• McAuley_index = exp(2.63 - 0.28 ln(I0 (muU/mL)) - 0.31 ln(TG (mmol/L)))

• Adipo_inv = -(FFA * I0 (muU/mL))

• Belfiore_inv_FFA = - 2 / (I0 (muU/mL) * FFA + 1)

Inversion Note: Most indices (VAI, LAP, TyG, TG/HDL, Adipo, Belfiore) are algebraically inverted from their original insulin RESISTANCE definitions so that more negative values consistently indicate worse adipose insulin sensitivity. Revised_QUICKI and McAuley_index are retained in their original orientation (already sensitivity indices; higher = better). See the vignette for detailed interpretation guidance.

Usage

adipo_is(
  data,
  col_map = NULL,
  normalize = "none",
  na_action = c("keep", "omit", "error"),
  verbose = TRUE,
  ...
)

Arguments

Value

A tibble with columns: Revised_QUICKI, VAI_Men_inv, VAI_Women_inv, TG_HDL_C_inv, TyG_inv, LAP_Men_inv, LAP_Women_inv, McAuley_index, Adipo_inv, Belfiore_inv_FFA. If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

References

Katz A, Nambi SS, Mather K, Baron AD, Follmann DA, Sullivan G, Quon MJ (2000). “Quantitative Insulin Sensitivity Check Index: A Simple, Accurate Method for Assessing Insulin Sensitivity in Humans.” Journal of Clinical Endocrinology & Metabolism, 85(7), 2402–2410. doi:10.1210/jcem.85.7.6661. Amato MC, Giordano C, Galia M, Criscimanna A, Vitabile S, Midiri M, Galluzzo A (2010). “Visceral Adiposity Index: A Reliable Indicator of Visceral Fat Function Associated with Cardiometabolic Risk.” Diabetes Care, 33(4), 920–922. doi:10.2337/dc09-1825. Kahn HS (2005). “The Lipid Accumulation Product Performs Better than Body Mass Index as an Indicator of Cardiovascular Risk in Women.” BMC Cardiovascular Disorders, 5(1), 26. doi:10.1186/1471-2261-5-26. Guerrero-Romero F, Simental-Mendía LE, González-Ortiz M, Martínez-Abundis E, Ramos-Zavala MG, Hernández-González SO, Jacques-Camarena O, Rodríguez-Morán M (2010). “The Product of Triglycerides and Glucose, a Simple Measure of Insulin Sensitivity. Comparison with the Euglycemic-Hyperinsulinemic Clamp.” Journal of Clinical Endocrinology & Metabolism, 95(7), 3347–3351. doi:10.1210/jc.2010-0288. Dobiášová M, Frohlich JJ (2001). “The Plasma Parameter Log(TG/HDL-C) as an Atherogenic Index: Correlation with Lipoprotein Particle Size and Esterification Rate in ApoB-Lipoprotein-Depleted Plasma.” Clinical Biochemistry, 34(7), 583–588. doi:10.1016/S0009-9120(01)00263-6. Belfiore F, Iannello S, Volpicelli G (1998). “Insulin Sensitivity Indices Calculated from Basal and OGTT-Related Insulin and Glucose Levels.” Molecular Genetics and Metabolism, 63(2), 134–141. doi:10.1006/mgme.1997.2658. Raynaud E, Pérez-Martin A, Brun J, Benhaddad AA, Mercier J (1999). “Fasting Plasma Insulin and Insulin Resistance Indices.” Diabetes & Metabolism, 25(6), 524–532. No DOI identified in Crossref/PubMed as of 2026-03-16; see URL, https://pubmed.ncbi.nlm.nih.gov/?term=Fasting+Plasma+Insulin+and+Insulin+Resistance+Indices.

Examples

df <- tibble::tibble(
  G0 = c(5.2, 6.1),      # mmol/L
  I0 = c(60, 110),       # pmol/L
  TG = c(1.2, 1.8),      # mmol/L
  HDL_c = c(1.3, 1.0),   # mmol/L
  FFA = c(0.4, 0.6),     # mmol/L
  waist = c(85, 102),    # cm
  bmi = c(24, 31)        # kg/m^2
)
cm <- as.list(names(df)); names(cm) <- names(df)
out <- adipo_is(df, cm, verbose = FALSE, na_action = "keep")

Description

Computes standard deviation (z) scores for anthropometric variables relative to a single (non-sex-stratified) reference set of means and standard deviations. Includes input validation, optional raw-value extreme screening/capping, configurable handling of extreme SDS values, NA row policies, optional concise summary output, and optional verbose progress messages.

Usage

adiposity_sds(
  data,
  col_map = NULL,
  ref,
  na_action = c("keep", "omit", "error"),
  extreme_action = c("cap", "NA", "error", "warn", "ignore"),
  sds_cap = 6,
  diagnostics = FALSE,
  warn_thresholds = list(na_prop = 0.05, extreme_prop = 0.01),
  id_col = NULL,
  return_summary = FALSE,
  verbose = TRUE,
  na_strategy = NULL,
  extreme_strategy = NULL
)

Arguments

Details

SDS are computed as: (observed - mean) / sd. Rows are removed only when na_action = 'omit'. Raw-value extreme screening (if enabled) is applied before SDS computation. Extreme SDS handling (cap / warn / error / ignore) is controlled by extreme_action. Legacy argument aliases (na_strategy, extreme_strategy) are soft-deprecated but still accepted.

Value

A tibble with one ⁠<var>_SDS⁠ column per reference variable, or a list when return_summary = TRUE.

Examples

ref <- list(BMI = c(mean = 23, sd = 4), waist = c(mean = 80, sd = 12))
df <- data.frame(BMI = c(25, NA, 60, 18), waist = c(85, 70, 300, 55))
adiposity_sds(df, ref)

Description

Computes sex-specific SDS (z-scores) for selected anthropometric variables using reference means and SDs provided separately for males and females.

Usage

adiposity_sds_strat(
  data,
  col_map,
  ref,
  na_action = c("keep", "omit", "error"),
  allow_partial = FALSE,
  prefix = "",
  verbose = TRUE
)

Arguments

Value

A tibble with one SDS column per retained variable: varname_SDS, where varname is the original variable name (optionally prefixed by prefix).

References

World Health Organization (1995). Physical Status: The Use and Interpretation of Anthropometry, volume 854 of Technical Report Series. World Health Organization. ISBN 9241208546. No DOI for this WHO report; see ISBN/URL, https://www.who.int/publications/i/item/9241208546.

Examples

ref <- list(
  M = list(BMI = c(mean=24.5, sd=3.8), waist = c(mean=88, sd=12)),
  F = list(BMI = c(mean=22.1, sd=4.2), waist = c(mean=76, sd=11))
)
df <- data.frame(BMI=c(25.2,21.8,27.1), waist=c(85,72,95), sex=c("M","F","M"))
adiposity_sds_strat(
  df,
  col_map = list(sex = "sex", vars = list(BMI = "BMI", waist = "waist")),
  ref = ref
)

Description

Compute all available HealthMarkers categories

Usage

all_health_markers(
  data,
  col_map,
  which = "all",
  include_insulin = TRUE,
  normalize = c("none", "z", "inverse", "range", "robust"),
  mode = c("both", "IS", "IR"),
  verbose = TRUE,
  na_action = c("keep", "omit", "error"),
  id_col = NULL,
  return_input = TRUE
)

Arguments

Details

Common group names for which include:

• "lipid", "liver", "glycemic", "mets", "oxidative"

• "bone", "allostatic_load", "nutrient", "vitamin", "vitamin_d_status"

• "renal", "ckd_stage", "kidney_kfre"

• "frailty_index", "charlson", "sarc_f"

• "nfl", "iAge", "calcium_corrected", "kyn_trp"

Value

Data frame. When return_input = TRUE (default): original columns plus all derived markers. When return_input = FALSE: only the newly computed columns (and id_col if specified).

Note

For academic / clinical references tied to each derived marker or index, consult the help pages of the source functions (e.g. ?allostatic_load, ?bone_markers, ?vitamin_markers, ?inflammatory_markers, etc.). This aggregator provides integration only and does not restate citations.

Aggregator wrapper. See underlying function help pages for full references across categories included by which.

Examples

# Quick smoke-test (lipid group only, no insulin)
df <- data.frame(TC = 200, HDL_c = 50, TG = 150, LDL_c = 120)
all_health_markers(df, col_map = list(), which = "lipid",
                   include_insulin = FALSE, normalize = "none",
                   verbose = FALSE, na_action = "keep")


# Lipid + liver groups
df <- data.frame(
  TC = 200, HDL_c = 50, TG = 150, LDL_c = 120,
  ALT = 30, AST = 20, BMI = 25
)
all_health_markers(df, col_map = list(), which = c("lipid","liver"),
                   include_insulin = FALSE, normalize = "none", mode = "both",
                   verbose = FALSE, na_action = "keep")

Description

Compute insulin sensitivity/resistance panels (fasting, OGTT, adipose, tracer/DXA)

Usage

all_insulin_indices(
  data,
  col_map = NULL,
  normalize = c("none", "z", "inverse", "range", "robust"),
  mode = c("both", "IS", "IR"),
  verbose = TRUE,
  na_action = c("keep", "omit", "error")
)

Arguments

Value

A tibble of IS (and/or IR_) columns.

Note

For scholarly references to specific indices (e.g., HOMA-IR, QUICKI, Raynaud, Belfiore, tracer-derived indices, adiposity-related IS metrics), consult the individual function help pages (e.g. ?fasting_is, ?ogtt_is, ?adipo_is, ?tracer_dxa_is). Citations are intentionally not duplicated here.

Aggregator wrapper. See underlying function help pages for full references: fasting_is(), ogtt_is(), adipo_is(), tracer_dxa_is().

References

Suleman S, Madsen AL, Ängquist LH, Schubert M, Linneberg A, Loos RJF, Hansen T, Grarup N (2024). “Genetic Underpinnings of Fasting and Oral Glucose-stimulated Based Insulin Sensitivity Indices.” The Journal of Clinical Endocrinology & Metabolism, 109(11), 2754–2763. doi:10.1210/clinem/dgae275.

Examples

# Quick smoke-test (fasting indices only)
df <- data.frame(G0 = 5.2, I0 = 60)
all_insulin_indices(df, normalize = "none", mode = "IS",
                    verbose = FALSE, na_action = "keep")


# Full panel with all supported inputs
df <- data.frame(
  G0 = 5.2, I0 = 60, G30 = 7.5, I30 = 90, G120 = 6.2, I120 = 80,
  TG = 1.5, HDL_c = 1.3, FFA = 0.3, waist = 85, weight = 70, bmi = 24,
  age = 40, sex = "M", rate_palmitate = 0.1, rate_glycerol = 0.2, fat_mass = 20
)
all_insulin_indices(df, col_map = list(
  G0="G0", I0="I0", G30="G30", I30="I30", G120="G120", I120="I120",
  TG="TG", HDL_c="HDL_c", FFA="FFA", waist="waist", weight="weight",
  bmi="bmi", age="age", sex="sex", rate_palmitate="rate_palmitate",
  rate_glycerol="rate_glycerol", fat_mass="fat_mass"
), normalize = "none", mode = "IS", verbose = FALSE, na_action = "keep")

Description

Computes a composite Allostatic Load (AL) score by flagging biomarkers that exceed user-specified high-risk thresholds (strict > when multiple biomarkers; inclusive >= when only one biomarker). Aligned with HM-CS v3: structured validation, diagnostic control, verbose reporting, and optional summary output.

Usage

allostatic_load(
  data,
  thresholds,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  return_summary = FALSE,
  verbose = TRUE
)

Arguments

Details

API pattern note: Unlike most HealthMarkers functions which follow the standard ⁠(data, col_map, ...)⁠ signature, allostatic_load() uses ⁠(data, thresholds, col_map = NULL, ...)⁠ because thresholds is a domain-specific required argument that cannot be inferred from column names alone. As a result, this function is not directly dispatchable through the standard all_health_markers() registry; a custom wrapper that supplies thresholds explicitly would be required.

Value

tibble with AllostaticLoad or list when return_summary = TRUE.

References

Seeman TE, Singer BH, Rowe JW, Horwitz RI, McEwen BS (1997). “Price of Adaptation—Allostatic Load and Its Health Consequences.” Archives of Internal Medicine, 157(19), 2259–2268. doi:10.1001/archinte.1997.00440400111013.

See Also

adiposity_sds, adiposity_sds_strat

Examples

df <- tibble::tibble(
  SBP = c(118, 142, 130),
  DBP = c(76, 92, 85),
  CRP = c(1.2, 4.8, 2.1)
)
thr <- list(SBP = 130, DBP = 85, CRP = 3)
allostatic_load(df, thresholds = thr, na_action = "keep", verbose = FALSE)

# Single biomarker uses inclusive >= rule
allostatic_load(df, thresholds = list(CRP = 3))

Description

Calculates the ratio of appendicular lean mass (ALM) to body mass index (BMI), and flags low muscle mass based on FNIH Sarcopenia Project cut-points.

Usage

alm_bmi_index(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  verbose = TRUE
)

Arguments

Details

ALM/BMI reflects muscle mass relative to body size. FNIH cut-points:

• Men: ALM/BMI < 0.789

• Women: ALM/BMI < 0.512

ALM should be in kilograms and BMI in kg/m^2.

Value

A tibble with:

• alm_bmi_ratio (numeric)

• low_muscle_mass (logical; TRUE if below sex-specific cut-point; NA if sex unknown or ratio NA)

References

McLean RR, Shardell MD, Alley DE, et al. (2014). “Criteria for clinically relevant weakness and low lean mass: FNIH Sarcopenia Project.” Journal of Gerontology A: Biological Sciences and Medical Sciences, 69(5), 576–583. doi:10.1093/gerona/glu012.

Examples

df <- data.frame(ALM_kg = c(7.2, 5.8, 6.5), BMI = c(24, 28, 22),
                 Sex = c("male", "female", "male"))
alm_bmi_index(df)

Description

Adult ADHD Self-Report Scale scoring

Usage

asrs_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "ASRS",
  partA_items = sprintf("asrs_%02d", 1:6),
  partA_thresholds = c(3, 3, 3, 4, 4, 4),
  partA_cutoff = 4,
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: ASRS_total, ASRS_partA_count, ASRS_partA_positive. Input columns are not included.

Note

Items are expected on a 0–4 scale (Never=0, Rarely=1, Sometimes=2, Often=3, Very Often=4). The default partA_thresholds follow the official WHO ASRS v1.1 guide: items 1–3 are positive at $\geq 3$ (Often or Very Often) and items 4–6 at $\geq 4$ (Very Often only).

References

Kessler RC, Adler LA, Ames M, Demler O, Faraone SV, Hiripi E, Howes MJ, Jin R, Secnik K, Spencer T, Üstün TB, Walters EE (2005). “The World Health Organization Adult ADHD Self-Report Scale (ASRS): A Short Screening Scale for Use in the General Population.” Psychological Medicine, 35(2), 245–256. doi:10.1017/S0033291704002892. Kessler RC, Adler L, Ames M, Demler O, Faraone SV, Hiripi E, Howes MJ, Jin R, Secnik K, Spencer T, Ustün TB, Walters EE (2006). “The Prevalence and Correlates of Adult ADHD in the United States: Results from the National Comorbidity Survey Replication.” American Journal of Psychiatry, 163(4), 716–723. doi:10.1176/ajp.2006.163.4.716. (prevalence study; ASRS used as instrument)

Examples

df <- data.frame(matrix(2, nrow = 1, ncol = 18))
names(df) <- sprintf("asrs_%02d", 1:18)
asrs_score(df)

Description

Calculates:

• AIP: Atherogenic Index of Plasma = log10(TG / HDL_c)

• CRI_I: Castelli Risk Index I = TC / HDL_c

• CRI_II: Castelli Risk Index II = LDL_c / HDL_c

Usage

atherogenic_indices(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  normalize = c("none", "log10"),
  verbose = TRUE
)

Arguments

Details

Behavior:

• Required keys: TG, HDL_c. Optional: TC, LDL_c.

• NA policy via na_action: "keep" (default), "omit" (drop rows with any NA in used lipids), "error".

• Extreme screening via check_extreme and extreme_action ("warn","cap","error","ignore","NA"). Default bounds (mg/dL) used only for screening: TG (0, 10000), HDL_c (0, 1000), LDL_c (0, 10000), TC (0, 10000). Note: All indices are unitless ratios; units cancel in computations.

• Emits progress via hm_inform() when verbose = TRUE or when package option enables logs.

Value

tibble with columns AIP, CRI_I, CRI_II. If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended.

References

Dobiášová M (2004). “Atherogenic Index of Plasma (AIP) log(Triglycerides/HDL-Cholesterol): Theoretical and Practical Implications.” Clinical Chemistry, 50(7), 1113–1115. doi:10.1373/clinchem.2004.033175. Castelli WP, Doyle JT, Gordon T, et al. (1977). “High-Density Lipoprotein Cholesterol and Other Lipids in Coronary Heart Disease: The Framingham Study.” American Journal of Medicine, 62(5), 707–714. doi:10.1016/0002-9343(77)90874-9.

Examples

df <- tibble::tibble(
  TG = c(150, 200),
  HDL_c = c(50, 40),
  TC = c(200, 220),
  LDL_c = c(120, 150)
)
cm <- list(TG = "TG", HDL_c = "HDL_c", TC = "TC", LDL_c = "LDL_c")
atherogenic_indices(df, col_map = cm)

Description

Barratt Impulsiveness Scale (key-driven)

Usage

bis_score(
  data,
  col_map = list(),
  key,
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "BIS",
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only (total and optional subscales). Input columns are not included.

References

Patton JH, Stanford MS, Barratt ES (1995). “Factor Structure of the Barratt Impulsiveness Scale.” Journal of Clinical Psychology, 51(6), 768–774. doi:10.1002/1097-4679(199511)51:6<768::AID-JCLP2270510607>3.0.CO;2-1.

Examples

bis_key <- list(items = sprintf("bis_%02d", 1:5), min_val = 1, max_val = 4)
df <- data.frame(bis_01 = 1, bis_02 = 2, bis_03 = 3, bis_04 = 4, bis_05 = 2)
bis_score(df, key = bis_key)

Description

Computes the BODE index (0-10) using FEV1 % predicted, 6-minute walk distance (6MWD), mMRC dyspnea scale, and BMI. Higher scores indicate worse prognosis in COPD.

Usage

bode_index(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  verbose = TRUE
)

Arguments

Details

Scoring components: FEV1 % predicted: >=65 = 0; 50-64 = 1; 36-49 = 2; <=35 = 3 6MWD (meters): >=350 = 0; 250-349 = 1; 150-249 = 2; <=149 = 3 mMRC dyspnea: 0-1 = 0; 2 = 1; 3 = 2; 4 = 3 BMI: >21 = 0; <=21 = 1

Value

tibble with bode_index (integer). NA if any required input missing (unless omitted).

References

Celli BR, Cote CG, Marin JM, Casanova C, Montes de Oca M, Mendez R, Pinto-Plata V, Cabral HJ (2004). “The BODE Index in Chronic Obstructive Pulmonary Disease.” The New England Journal of Medicine, 350, 1005–1012. doi:10.1056/NEJMoa021322.

Examples

df <- data.frame(FEV1pct = c(68, 45, 30), Walk_m = c(400, 280, 140),
                 mMRC = c(1, 2, 3), BMI = c(24, 19, 18))
bode_index(df, col_map = list(fev1_pct = "FEV1pct", sixmwd = "Walk_m",
                              mmrc = "mMRC", bmi = "BMI"))

Description

Given DXA, anthropometry, and optional bone-turnover markers, computes:

• OSTA: (weight - age) x 0.2

• ALMI: Appendicular Lean Mass Index = ALM / height^2

• FMI: Fat Mass Index = FM / height^2

• BMD_Tscore: (BMD - ref_mean) / ref_sd and (if in col_map + data) passes through: TBS, HSA, PINP, CTX, BSAP, Osteocalcin.

Usage

bone_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)

Arguments

Details

Notes:

• Units: height in meters; ALM, FM, weight in kilograms; BMD in g/cm^2; ALMI/FMI in kg/m^2.

• Non-finite values are treated as NA; division by zero is prevented by input checks.

• BMD_ref_mean and BMD_ref_sd must be supplied by the user from an appropriate reference population (for example, study-specific values or external norms such as NHANES).

Value

A tibble with columns: OSTA, ALMI, FMI, BMD_Tscore, and optionally TBS, HSA, PINP, CTX, BSAP, Osteocalcin (in that order).

References

Koh LK, Ben Sedrine W, Torralba TP, Kung A, others (2001). “A Simple Tool to Identify Asian Women at Increased Risk of Osteoporosis.” Osteoporosis International, 12(8), 699–705. doi:10.1007/s001980170070. World Health Organization (1994). Assessment of Fracture Risk and Its Application to Screening for Postmenopausal Osteoporosis, volume 843 of Technical Report Series. World Health Organization. No DOI for this WHO report; see URL, https://iris.who.int/handle/10665/39142.

Examples

library(tibble)
df <- tibble(
  age = c(60, 72), weight = c(65, 50), height = c(1.65, 1.58),
  ALM = c(18.2, 14.7), FM = c(22.0, 20.5),
  BMD = c(0.95, 0.80), BMD_ref_mean = c(1.00, 1.00), BMD_ref_sd = c(0.12, 0.12)
)
col_map <- list(
  age = "age", weight = "weight", height = "height",
  ALM = "ALM", FM = "FM", BMD = "BMD",
  BMD_ref_mean = "BMD_ref_mean", BMD_ref_sd = "BMD_ref_sd"
)
bone_markers(df, col_map)

Description

Computes per-variable SDS as (x - mean) / sd using supplied reference statistics. Includes input validation, NA/error handling, data quality warnings, and verbose progress via the package logger (hm_inform), aligned with HM-CS v3.

Usage

calc_sds(
  data,
  vars,
  ref,
  id_col = NULL,
  sds_cap = 6,
  na_strategy = c("omit", "error", "keep"),
  extreme_strategy = c("cap", "warn", "error", "NA"),
  warn_thresholds = list(na_prop = 0.05, extreme_prop = 0.01),
  return = c("data", "list"),
  verbose = TRUE,
  na_action = NULL,
  check_extreme = TRUE,
  extreme_action = NULL
)

Arguments

Details

Derivation: for each requested variable, SDS is calculated as (observed_value - reference_mean) / reference_sd using user-supplied reference statistics in ref.

Usage note: this function does not derive normative reference values internally. Users should provide ref from the target population (preferred), or from an external source matched as closely as possible on age/sex/ethnicity/context. Interpretability depends on the quality and relevance of those supplied reference means and SDs.

By default, returns a tibble with added ⁠[var]_sds⁠ columns (tidyverse-friendly). For backward compatibility, you can request the previous list output.

Value

• If return = "data" (default): a tibble with added ⁠[var]_sds⁠ columns.

• If return = "list": a list with:

  • data: tibble with added SDS columns

  • summary: list with input/output row counts, omitted rows, total extremes, and per-variable summary

  • warnings: character vector of warning messages emitted

Examples

ref <- data.frame(
  variable = c("bmi","sbp"),
  mean     = c(25, 120),
  sd       = c(4, 15)
)
df <- data.frame(
  id  = 1:6,
  bmi = c(24, 30, NA, 29, 10, 26),
  sbp = c(118, 200, 119, 121, 500, 120)
)
out_tbl <- calc_sds(
  data = df,
  vars = c("bmi","sbp"),
  ref = ref,
  id_col = "id",
  na_strategy = "omit",
  extreme_strategy = "cap",
  sds_cap = 6,
  verbose = FALSE
)

Description

Computes the Charlson Comorbidity Index by summing weighted comorbidities.

Usage

charlson_index(
  data,
  col_map = list(mi = "mi", chf = "chf", pvd = "pvd", stroke = "stroke", dementia =
    "dementia", copd = "copd", rheum = "rheum", ulcer = "ulcer", mild_liver =
    "mild_liver", diabetes = "diabetes", diab_comp = "diab_comp", hemiplegia =
    "hemiplegia", renal = "renal", cancer = "cancer", leukemia = "leukemia", lymphoma =
    "lymphoma", sev_liver = "sev_liver", metastatic_cancer = "metastatic_cancer", hiv =
    "hiv"),
  verbose = TRUE,
  na_action = c("keep", "omit", "error", "ignore", "warn")
)

Arguments

Details

The Charlson Index predicts 10-year mortality by summing weighted comorbidities. We implement the canonical 19-condition, weight scheme:

• 1 point: myocardial infarction, congestive heart failure, peripheral vascular disease, cerebrovascular disease (stroke), dementia, chronic pulmonary disease (COPD), rheumatologic disease, peptic ulcer disease

• 2 points: hemiplegia/paraplegia, moderate/severe renal disease, any malignancy (non-metastatic), leukemia, lymphoma, diabetes with complications

• 3 points: moderate/severe liver disease

• 6 points: metastatic solid tumor, AIDS/HIV

To avoid double counting paired conditions, the following use the maximum applicable weight:

• Diabetes: max(1 * diabetes without complications, 2 * diabetes with complications)

• Liver disease: max(1 * mild liver disease, 3 * moderate/severe liver disease)

• Cancer: max(2 * non-metastatic solid tumor, 6 * metastatic solid tumor)

Age points are not included here and can be added separately if needed.

Value

A tibble with one column: charlson_index (integer total score; NA if any required input is NA and na_action != "omit").

References

Charlson ME, Pompei P, Ales KL, MacKenzie CR (1987). “A New Method of Classifying Prognostic Comorbidity in Longitudinal Studies: Development and Validation.” Journal of Chronic Diseases, 40(5), 373–383. doi:10.1016/0021-9681(87)90171-8.

Examples

patient <- tibble::tibble(
  mi=0, chf=0, pvd=0, stroke=0, dementia=0, copd=0, rheum=0, ulcer=0,
  mild_liver=0, diabetes=0, diab_comp=1, hemiplegia=0, renal=1,
  cancer=0, leukemia=0, lymphoma=0, sev_liver=0, metastatic_cancer=0, hiv=0
)
charlson_index(
  patient,
  col_map = as.list(stats::setNames(names(patient), names(patient)))
)

Description

Categorizes eGFR into G1-G5, albuminuria into A1-A3 (by UACR mg/g), and maps KDIGO risk.

Usage

ckd_stage(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)

Arguments

Value

Tibble with CKD_stage, Albuminuria_stage, KDIGO_risk.

References

Kidney Disease: Improving Global Outcomes (KDIGO) CKD Work Group (2013). “KDIGO 2012 Clinical Practice Guideline for the Evaluation and Management of Chronic Kidney Disease.” Kidney International Supplements, 3(1), 1–150. doi:10.1038/kisup.2012.73. Related synopsis: Stevens and Levin (2013), Ann Intern Med, doi:10.7326/0003-4819-158-11-201306040-00007, https://kdigo.org/guidelines/ckd-evaluation-and-management/.

Examples

df <- data.frame(eGFR = c(95, 50), UACR = c(10, 200))
ckd_stage(df, list(eGFR = "eGFR", UACR = "UACR"))

Description

Cognitive composite (z-mean or PCA1)

Usage

cognitive_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  method = c("z_mean", "pca1"),
  prefix = "cog",
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: ⁠{prefix}_z_mean⁠ or ⁠{prefix}_pca1⁠. Input columns are not included.

Examples

df <- data.frame(task_a = c(1, 2), task_b = c(2, 3), task_c = c(3, 4))
cm <- list(tasks = list(
  task_a = "task_a",
  task_b = "task_b",
  task_c = "task_c"
))
cognitive_score(df, col_map = cm, method = "z_mean")

Description

Calculates the albumin-adjusted (corrected) serum calcium level, accounting for hypoalbuminemia, using the Payne formula.

Usage

corrected_calcium(
  data,
  col_map = NULL,
  units = c("auto", "conventional", "si"),
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  verbose = TRUE
)

Arguments

Details

Payne formula (conventional units): Corrected Ca (mg/dL) = measured Ca (mg/dL) + 0.8 * (4.0 - albumin (g/dL)). If inputs appear to be in SI units (calcium mmol/L, albumin g/L), they are converted to mg/dL and g/dL (using 1 mmol/L ~= 4 mg/dL; 1 g/L = 0.1 g/dL) for the correction and converted back to mmol/L for output.

Value

A tibble with one column: corrected_calcium (numeric, in mg/dL for conventional input or mmol/L for SI / auto-SI input).

References

Payne RB, Little AJ, Williams RB, Milner JR (1973). “Interpretation of serum calcium in patients with abnormal serum proteins.” British Medical Journal, 4(5893), 643–646. doi:10.1136/bmj.4.5893.643.

Examples

df <- data.frame(Ca = c(2.3, 2.5, 2.1), Alb = c(38, 42, 30))
corrected_calcium(df)

Description

Computes log10(TG / HDL_c) with input validation and HM-CS NA handling.

Usage

cvd_marker_aip(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)

Arguments

Value

A tibble with columns model = "AIP" and value.

References

Dobiášová M (2004). “Atherogenic Index of Plasma (AIP) log(Triglycerides/HDL-Cholesterol): Theoretical and Practical Implications.” Clinical Chemistry, 50(7), 1113–1115. doi:10.1373/clinchem.2004.033175.

Examples

df <- data.frame(TG = c(150, 200), HDL_c = c(50, 40))
cvd_marker_aip(df)

Description

Returns ApoB as a proxy for LDL particle number with HM-CS NA handling.

Usage

cvd_marker_ldl_particle_number(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)

Arguments

Value

A tibble with columns model = "LDL_PN" and value.

Examples

df <- data.frame(ApoB = c(80, 120, 100))
cvd_marker_ldl_particle_number(df)

Description

Dispatch to the appropriate risk or marker function, or run all of them. Includes basic argument validation and robust fallback to NA rows if individual calculators fail.

Usage

cvd_risk(
  data,
  model = c("ALL", "ASCVD", "QRISK3", "Stroke", "RiskScorescvd", "AIP", "LDL_PN"),
  year = 10,
  ...,
  verbose = TRUE
)

Arguments

Value

A tibble.

Examples

df <- data.frame(TG = c(150, 200), HDL_c = c(50, 40))
cvd_risk(df, model = "AIP")

Description

Wrapper around the PooledCohort ASCVD calculators with added input validation, optional data-quality warnings, and quiet failure to NA if the backend errors.

Usage

cvd_risk_ascvd(
  data,
  year = 10,
  col_map = NULL,
  na_warn_prop = 0.2,
  verbose = TRUE,
  ...
)

Arguments

Value

A tibble with columns model, year, risk (percentage).

References

Goff DC, Lloyd-Jones DM, Bennett G, Coady S, D'Agostino RB, et al. (2014). “2013/2014 ACC/AHA Guideline on the Assessment of Cardiovascular Risk.” Circulation, 129(25 Suppl 2), S49–S73. doi:10.1161/01.cir.0000437741.48606.98. Pooled Cohort Equations; ACC/AHA Task Force on Practice Guidelines.

Examples

df <- tibble::tibble(
  age = 55, sex = 1, race = "white", smoker = FALSE,
  total_chol = 200, HDL_c = 50, sbp = 140, bp_treated = FALSE,
  diabetes = FALSE, bmi = 27
)
if (requireNamespace("PooledCohort", quietly = TRUE)) {
  cvd_risk_ascvd(df, year = 10, verbose = TRUE)
}

Description

Wrapper around QRISK3::QRISK3_2017() that auto-generates a patid if one is not supplied. Adds input validation and quiet failure to NA on backend error.

Usage

cvd_risk_qrisk3(data, ..., patid = NULL, na_warn_prop = 0.2, verbose = TRUE)

Arguments

Value

A tibble with columns model, year, risk.

References

Hippisley-Cox J, Coupland C, Brindle P, et al. (2017). “Development and validation of QRISK3 risk prediction algorithms.” BMJ, 357, j2099. doi:10.1136/bmj.j2099.

Examples

if (requireNamespace("QRISK3", quietly = TRUE)) {
    df <- data.frame(
      gender = 1L, age = 55L,
      atrial_fibrillation = 0L, atypical_antipsy = 0L,
      regular_steroid_tablets = 0L, erectile_disfunction = 0L,
      migraine = 0L, rheumatoid_arthritis = 0L,
      chronic_kidney_disease = 0L, severe_mental_illness = 0L,
      systemic_lupus_erythematosis = 0L, blood_pressure_treatment = 0L,
      diabetes1 = 0L, diabetes2 = 0L,
      weight = 80, height = 175,
      ethnicity = 1L, heart_attack_relative = 0L,
      cholesterol_HDL_ratio = 4.2, systolic_blood_pressure = 130,
      std_systolic_blood_pressure = 7, smoke = 0L, townsend = 0
    )
    cvd_risk_qrisk3(df)
  }

Description

Passthrough to RiskScorescvd::calc_scores() with graceful fallback to NA.

Usage

cvd_risk_scorescvd(data, ...)

Arguments

Value

Object returned by RiskScorescvd::calc_scores().

Examples

if (requireNamespace("RiskScorescvd", quietly = TRUE)) {
    df <- data.frame(
      Age = 55, Sex = 0, Smoking_status = 1,
      systolic.bp = 140, Total_cholesterol = 5.5,
      HDL.cholesterol = 1.3
    )
    cvd_risk_scorescvd(df)
  }

Description

Wrapper around PooledCohort::predict_10yr_stroke_risk() with quiet fallback to NA if the backend errors.

Usage

cvd_risk_stroke(data, col_map = NULL, na_warn_prop = 0.2, verbose = TRUE, ...)

Arguments

Value

A tibble with model, year, risk.

References

Goff DC, Lloyd-Jones DM, Bennett G, Coady S, D'Agostino RB, et al. (2014). “2013/2014 ACC/AHA Guideline on the Assessment of Cardiovascular Risk.” Circulation, 129(25 Suppl 2), S49–S73. doi:10.1161/01.cir.0000437741.48606.98. Pooled Cohort Equations; ACC/AHA Task Force on Practice Guidelines.

Examples

if (requireNamespace("PooledCohort", quietly = TRUE)) {
  df <- data.frame(age = 55, sex = 1, race = "white", smoker = FALSE,
    total_chol = 200, HDL_c = 50, sbp = 140, bp_treated = FALSE,
    diabetes = FALSE, bmi = 27)
  cvd_risk_stroke(df)
}

Description

Compute 10 fasting indices from glucose (mmol/L) and insulin (pmol/L): Fasting_inv, Raynaud, HOMA_IR_inv, FIRI, QUICKI, Belfiore_basal, Ig_ratio_basal, Isi_basal, Bennett, HOMA_IR_rev_inv. Units converted internally: G0_mg = G0*18 (mg/dL), I0_u = I0/6 (muU/mL).

Usage

fasting_is(
  data,
  col_map = NULL,
  normalize = c("none", "z", "inverse", "range", "robust"),
  na_action = c("keep", "omit", "error", "warn"),
  verbose = TRUE
)

Arguments

Value

Tibble with 10 columns (indices listed above). If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

References

Matthews DR, Hosker JP, Rudenski AS, Naylor BA, Treacher DF, Turner RC (1985). “Homeostasis Model Assessment: Insulin Resistance and Beta-Cell Function from Fasting Plasma Glucose and Insulin Concentrations in Man.” Diabetologia, 28(7), 412–419. doi:10.1007/BF00280883. Katz A, Nambi SS, Mather K, Baron AD, Follmann DA, Sullivan G, Quon MJ (2000). “Quantitative Insulin Sensitivity Check Index: A Simple, Accurate Method for Assessing Insulin Sensitivity in Humans.” Journal of Clinical Endocrinology & Metabolism, 85(7), 2402–2410. doi:10.1210/jcem.85.7.6661. Raynaud E, Pérez-Martin A, Brun J, Benhaddad AA, Mercier J (1999). “Fasting Plasma Insulin and Insulin Resistance Indices.” Diabetes & Metabolism, 25(6), 524–532. No DOI identified in Crossref/PubMed as of 2026-03-16; see URL, https://pubmed.ncbi.nlm.nih.gov/?term=Fasting+Plasma+Insulin+and+Insulin+Resistance+Indices. Avignon A, Charles M, Rabasa-Lhoret R, et al. (1999). “Assessment of Insulin Sensitivity from Oral Glucose Tolerance Test in Normal Subjects and in Insulin-Resistant Patients.” International Journal of Obesity, 23(5), 512–517. doi:10.1038/sj.ijo.0800864. Belfiore F, Iannello S, Volpicelli G (1998). “Insulin Sensitivity Indices Calculated from Basal and OGTT-Related Insulin and Glucose Levels.” Molecular Genetics and Metabolism, 63(2), 134–141. doi:10.1006/mgme.1997.2658. Sluiter D, Erkelens DW, Reitsma WD, Doorenbos H (1976). “Glucose Tolerance and Insulin Release: A Mathematical Approach.” Diabetes, 25, 245–249. doi:10.2337/diabetes.25.4.245. Hanson RL, Pratley RE, Bogardus C, Narayan KMV, Roumain J, Imperatore G, Fagot-Campagna A, Pettitt DJ, Bennett PH, Knowler WC (2000). “Evaluation of Simple Indices of Insulin Sensitivity and Insulin Secretion for Use in Epidemiologic Studies.” American Journal of Epidemiology, 151(2), 190–198. doi:10.1093/oxfordjournals.aje.a010187. Anderson RL, Hamman RF, Savage PJ, Saad MF, Laws A, Kades WW, Sands RE, Cefalu WT (1995). “Exploration of Simple Measures of Insulin Resistance.” American Journal of Epidemiology, 142(7), 724–732. doi:10.1093/aje/142.7.724.

Examples

# Minimal example (units: G0 in mmol/L, I0 in pmol/L)
df <- data.frame(G0 = c(5.2, 6.1, 4.8), I0 = c(60, 120, 80))
res <- fasting_is(df, col_map = list(G0 = "G0", I0 = "I0"))
head(res)

# With NA handling
df2 <- data.frame(G0 = c(5.0, NA), I0 = c(90, 150))
fasting_is(df2, col_map = list(G0 = "G0", I0 = "I0"), na_action = "keep")

Description

Thin wrapper around the di package's di() that:

• Validates inputs and arguments.

• Coerces tibbles to base data.frames (for di()'s class checks).

• Auto-selects numeric deficit columns when cols = NULL (excluding age if supplied).

• Optionally scans for missing/out-of-range values with warnings or errors.

• Provides step-by-step verbose output and a completion summary.

• Optionally returns a tidy tibble instead of the original list.

Usage

frailty_index(
  data,
  cols = NULL,
  invert = NULL,
  rescale = TRUE,
  age = NULL,
  rescale.custom = NULL,
  rescale.avoid = NULL,
  bins = 7,
  visible = FALSE,
  na_action = c("ignore", "warn", "error", "keep", "omit"),
  na_warn_prop = 0.2,
  return = c("list", "data"),
  verbose = TRUE
)

Arguments

Details

Background The Frailty Index (FI) is computed as the proportion of health deficits present in an individual across a set of candidate deficits. The approach was introduced and formalized by Rockwood and Mitnitski and subsequently standardized for construction and reporting.

Value

• If return = "list" (default): the object returned by di::di (typically a list with di and columns).

• If return = "data": a tibble with di and the selected columns.

References

Mitnitski AB, Mogilner AJ, Rockwood K (2001). “Accumulation of Deficits as a Proxy Measure of Aging.” The Scientific World Journal, 1, 323–336. doi:10.1100/tsw.2001.58. Rockwood K, Mitnitski A (2007). “Frailty in Relation to the Accumulation of Deficits.” Journals of Gerontology Series A, 62(7), 722–727. doi:10.1093/gerona/62.7.722. Searle SD, Mitnitski A, Gahbauer EA, Gill TM, Rockwood K (2008). “A Standard Procedure for Creating a Frailty Index.” BMC Geriatrics, 8, 24. doi:10.1186/1471-2318-8-24.

Examples

# Minimal example (runs only if the 'di' package is installed)
if (requireNamespace("di", quietly = TRUE)) {
  df <- data.frame(
    age = c(70, 75, 80),
    d1 = c(0, 1, 1),
    d2 = c(0.2, 0.8, 1.0),
    d3 = c(TRUE, FALSE, TRUE)
  )
  # Auto-select numeric deficits; returns list (di, columns)
  res <- frailty_index(df, cols = NULL, age = "age", verbose = TRUE)
  # Tidy tibble return
  tb  <- frailty_index(df, cols = c("d1","d2","d3"), age = "age",
                       return = "data", verbose = TRUE)
}

Description

Estimates the 10-year probabilities of major osteoporotic and hip fracture using a simplified, non-validated approximation based on FRAX risk factors. This is for development/demo only and does not implement the proprietary FRAX algorithm.

Usage

frax_score(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  country = NULL,
  verbose = TRUE
)

Arguments

Details

Important: this function is an educational placeholder and must not be used for clinical decision-making, patient counseling, or guideline-based treatment selection.

Value

Tibble with frax_major_percent and frax_hip_percent.

Examples

df <- data.frame(Age = c(65, 72, 58), Sex = c("female", "female", "male"))
frax_score(df)

Description

GAD-7 scoring

Usage

gad7_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "GAD7",
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: GAD7_total and GAD7_severity (factor). Input columns are not included.

References

Spitzer RL, Kroenke K, Williams JBW, Löwe B (2006). “A Brief Measure for Assessing Generalized Anxiety Disorder: The GAD-7.” Archives of Internal Medicine, 166(10), 1092–1097. doi:10.1001/archinte.166.10.1092. Plummer F, Manea L, Trepel D, McMillan D (2016). “Screening for Anxiety Disorders with the GAD-7 and GAD-2: A Systematic Review and Diagnostic Meta-Analysis.” General Hospital Psychiatry, 39, 24–31. doi:10.1016/j.genhosppsych.2015.11.005. (validation meta-analysis)

Examples

df <- data.frame(gad7_01 = 0, gad7_02 = 1, gad7_03 = 2, gad7_04 = 1,
                 gad7_05 = 0, gad7_06 = 1, gad7_07 = 2)
gad7_score(df)

Description

GHQ-12 scoring (Likert or binary)

Usage

ghq12_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "GHQ12",
  method = c("likert", "binary"),
  case_cutoff_binary = 3,
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: GHQ12_total_likert (likert method) or GHQ12_total_binary and GHQ12_case_binary (binary method). Input columns are not included.

References

Goldberg DP, Williams P (1988). A User's Guide to the General Health Questionnaire. NFER-Nelson, Windsor, UK.

Examples

df <- data.frame(ghq12_01 = 0, ghq12_02 = 1, ghq12_03 = 2, ghq12_04 = 1,
                 ghq12_05 = 0, ghq12_06 = 1, ghq12_07 = 0, ghq12_08 = 1,
                 ghq12_09 = 2, ghq12_10 = 1, ghq12_11 = 0, ghq12_12 = 1)
ghq12_score(df, method = "likert")

Description

Given fasting labs and anthropometry, computes:

• SPISE (Single-Point Insulin Sensitivity Estimator)

• METS_IR (Metabolic Score for Insulin Resistance)

• prediabetes flag (HbA1c >= 42 mmol/mol)

• diabetes flag (HbA1c >= 48 mmol/mol)

• HOMA_CP (C-peptide-based HOMA-IR variant; operational formula, see notes)

• LAR (Leptin/Adiponectin Ratio)

• ASI (Adiponectin Sensitivity Index; adiponectin/insulin)

• TyG_index (Triglyceride-Glucose Index)

Usage

glycemic_markers(
  data,
  col_map = NULL,
  na_action = c("ignore", "warn", "error", "keep", "omit"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

Details

Assumed units (no automatic conversion of inputs except where noted):

• HDL_c, TG: mmol/L (TyG internally converts TG to mg/dL via 88.57)

• BMI: kg/m^2

• glucose, G0: mmol/L (TyG internally converts glucose to mg/dL via 18)

• HbA1c: mmol/mol

• C_peptide, I0: pmol/L (HOMA_CP uses I-like conversion factor 6 as in insulin muU/mL; see notes)

• leptin, adiponectin: ng/mL

These indices are intended for research and feature-engineering applications. The prediabetes and diabetes flags apply standard HbA1c cut-offs (WHO/IDF criteria) but this function is not validated as a clinical diagnostic tool.

Quality controls and options:

• Input validation ensures required variables exist and are numeric-coercible.

• Non-numeric inputs are coerced to numeric with a warning (NAs introduced reported).

• Missing or non-finite inputs are handled via na_action.

• Logs and divisions are computed safely (non-positive arguments yield NA).

• Physiological range notes are printed when verbose = TRUE (values are not altered).

• Verbose mode prints step-by-step progress and a completion summary.

Optional marker detection and pre-computation (one level deep): When col_map = NULL (default), column names are inferred automatically. The seven optional keys (glucose, HbA1c, C_peptide, G0, I0, leptin, adiponectin) are computed only when present in data. If BMI is absent but weight (kg) and height (m or cm) are present, BMI is computed automatically. If glucose is absent but G0 column exists (or vice versa), the missing key is derived via alias. With verbose = TRUE (default), the function reports: column mapping, what is missing and which raw inputs could provide it, which indices will be NA and why, any physiological range notes, and a per-column results summary.

Notes on HOMA_CP:

• This function retains the package's existing operational formula: HOMA_CP = (G0 (mmol/L) * (C_peptide (pmol/L) / 6)) / 22.5 which mirrors HOMA-IR's structure using a 6 pmol/muU scaling used for insulin. Users should verify unit conventions for their datasets; alternative C-peptide HOMA implementations exist (e.g., HOMA2-CP).

Value

A tibble with columns:

• SPISE, METS_IR, prediabetes, diabetes, HOMA_CP, LAR, ASI, TyG_index If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

References

Paulmichl K, Hatunic M, Höbaus C, et al. (2016). “Modification and Validation of the Triglyceride-to–HDL Cholesterol Ratio as a Surrogate of Insulin Sensitivity in White Juveniles and Adults without Diabetes Mellitus: The Single Point Insulin Sensitivity Estimator (SPISE).” Clinical Chemistry, 62(9), 1211–1219. doi:10.1373/clinchem.2016.257436. Bello-Chavolla OY, Almeda-Valdes P, García-Sánchez A, et al. (2018). “METS-IR, a novel score to evaluate insulin sensitivity, is predictive of visceral adiposity and incident type 2 diabetes.” European Journal of Endocrinology, 178(5), 533–544. doi:10.1530/EJE-17-0883. Frühbeck G, Catalan V, Rodríguez A, Ramón Sánchez-Recalde Á, Becerril S, Sánchez-González Á, Baena N, Valentí-Azcárate F, Burrell MA, Salvador J (2019). “Adiponectin-leptin Ratio is a Functional Biomarker of Adipose Tissue Inflammation.” Nutrients, 11(2), 454. doi:10.3390/nu11020454. Matthews DR, Hosker JP, Rudenski AS, Naylor BA, Treacher DF, Turner RC (1985). “Homeostasis Model Assessment: Insulin Resistance and Beta-Cell Function from Fasting Plasma Glucose and Insulin Concentrations in Man.” Diabetologia, 28(7), 412–419. doi:10.1007/BF00280883. Simental-Mendía LE, Rodríguez-Morán M, Guerrero-Romero F (2008). “The Product of Fasting Glucose and Triglycerides as Surrogate for Identifying Insulin Resistance.” Metabolic Syndrome and Related Disorders, 6(4), 299–304. doi:10.1089/met.2008.0034. Furler SM, Gan SK, Poynten AM, Chisholm DJ, Campbell LV, Kriketos AD (2006). “Relationship of Adiponectin with Insulin Sensitivity in Humans, Independent of Lipid Availability.” Obesity, 14(2), 228–234. doi:10.1038/oby.2006.29.

Examples

# Quick smoke-test
df <- data.frame(glucose = 5.6, HbA1c = 44, G0 = 5.5, I0 = 60,
                 HDL_c = 1.2, TG = 1.5, BMI = 24)
glycemic_markers(df, verbose = FALSE)


df <- tibble::tibble(
  HDL_c       = c(1.0, 1.3),
  TG          = c(1.3, 2.0),
  BMI         = c(24, 30),
  glucose     = c(5.6, 7.1),
  HbA1c       = c(44, 38),
  C_peptide   = c(300, 500),
  G0          = c(5.5, 6.2),
  I0          = c(60, 120),
  leptin      = c(10, 20),
  adiponectin = c(8, 5)
)
glycemic_markers(df)
glycemic_markers(df, verbose = FALSE)
glycemic_markers(df, na_action = "omit", verbose = FALSE)

Description

Lightweight summary for numeric columns: n, n_na, mean, sd, median, p25, p75.

Usage

health_summary(x, cols = NULL)

Arguments

Value

A tibble with one row per summarized column.

Examples

df <- data.frame(a = c(1, 2, NA), b = c(3, 4, 5), c = factor("x"))
health_summary(df)

Description

Scans the column names of your data frame against the internal synonym dictionary used by all HealthMarkers functions and prints a formatted report showing which internal keys were matched automatically and which were not found. The function uses five matching layers in order:

1. User-supplied (via col_map) — always wins.

2. Exact synonym match — column name is in the synonym list.

3. Case-insensitive exact — same, ignoring upper/lower case.

4. Column contains synonym — data column name contains a synonym as a whole word (e.g.\ "trig_baseline" matches "trig").

5. Synonym contains column — a synonym contains the column name as a whole word (e.g.\ "TG_fasting" synonym matches column "TG").

6. Fuzzy (opt-in via fuzzy = TRUE) — Levenshtein-based approximate matching as a last resort.

The function returns the matched mappings invisibly as a named list that can be passed directly as the col_map argument to any HealthMarkers function.

Usage

hm_col_report(
  data,
  col_map = NULL,
  verbose = TRUE,
  fuzzy = FALSE,
  show_unmatched = FALSE
)

Arguments

Value

Invisibly returns a named list: internal key $\to$ matched data-column name. Keys that were not found are omitted. You can assign this to col_map and pass it to any HealthMarkers function.

Examples

## Not run: 
# Basic diagnostic
hm_col_report(my_data)

# Fuzzy matching + show all unmatched
hm_col_report(my_data, fuzzy = TRUE, show_unmatched = TRUE)

# Capture the result as a ready-to-use col_map
cm <- hm_col_report(my_data, verbose = FALSE)
all_health_markers(my_data, col_map = cm)

## End(Not run)

Description

A convenience wrapper around normalize_vec() that applies a normalisation method to every selected numeric column in a data frame and returns the modified data frame. The most common use-case is to normalise the output of any HealthMarkers function — especially domain functions such as glycemic_markers(), lipid_markers(), or renal_markers() whose internal normalize argument currently has no effect.

Usage

hm_normalize(
  data,
  cols = NULL,
  method = c("z", "inverse", "range", "robust"),
  skip_cols = NULL,
  ...
)

Arguments

Value

The input data with the selected columns replaced by their normalised values. Class (tibble, data.frame, etc.) is preserved.

See Also

normalize_vec() for single-vector normalisation.

Examples

# Build a tiny data frame with pre-computed marker columns
df <- data.frame(
  age    = c(45, 52, 61),
  HOMA_IR = c(1.2, 3.4, 2.1),
  TyG     = c(8.1, 9.0, 8.6),
  NLR     = c(2.1, 3.5, 1.8)
)

marker_cols <- c("HOMA_IR", "TyG", "NLR")

# z-score normalise marker columns only
hm_normalize(df, cols = marker_cols, method = "z")

# Inverse-normal transform, leaving age untouched
hm_normalize(df, method = "inverse", skip_cols = "age")

Description

Ratios computed:

• FAI = (total_testosterone / SHBG) * 100

• LH_FSH = LH / FSH

• E2_P = estradiol / progesterone

• T3_T4 = free_T3 / free_T4

• ARR = aldosterone / renin

• Ins_Glu = insulin / glucagon

• GH_IGF1 = GH / IGF1

• PRL_T = prolactin / total_testosterone

• CAR_slope = (cortisol_30 - cortisol_0) / 30

Usage

hormone_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "warn", "ignore"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

Details

Some inputs may be inferred when missing (for example, free_T3 from TSH + free_T4, or GH from IGF1) using internal heuristics. These inferred values are intended for exploratory feature engineering only and must not be treated as clinical substitutes for directly measured assays. Ratios such as FAI, ARR, and CAR_slope have established literature usage; several other outputs are simple arithmetic composites included for feature-engineering convenience and may not have a single canonical derivation paper.

Value

Tibble with one column per computable ratio. If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

References

Sowers MR, Zheng H, McConnell D, Nan B, Karvonen-Gutierrez CA, Randolph JF (2009). “Testosterone, sex hormone-binding globulin and free androgen index among adult women: chronological and ovarian aging.” Human Reproduction, 24(9), 2276–2285. doi:10.1093/humrep/dep209. Funder JW, Carey RM, Mantero F, Murad MH, Reincke M, Shibata H, Stowasser M, Young WF (2016). “The Management of Primary Aldosteronism: Case Detection, Diagnosis, and Treatment: An Endocrine Society Clinical Practice Guideline.” The Journal of Clinical Endocrinology & Metabolism, 101(5), 1889–1916. doi:10.1210/jc.2015-4061. Clow A, Thorn L, Evans P, Hucklebridge F (2004). “The awakening cortisol response: methodological issues and significance.” Stress, 7(1), 29–37. doi:10.1080/10253890410001667205.

Examples

df <- data.frame(
  TT = c(15, 12), SHBG = c(40, 35), LH = c(5, 6), FSH = c(4, 5),
  E2 = c(100, 120), Prog = c(0.5, 0.6), fT3 = c(4.5, 4.2),
  fT4 = c(15, 14), Aldo = c(200, 180), Renin = c(10, 12),
  Ins = c(60, 70), Gluc = c(8, 9), GH = c(1.2, 1.0),
  IGF1 = c(180, 160), Prl = c(10, 12), Cort0 = c(400, 380),
  Cort30 = c(600, 580)
)
col_map <- list(
  total_testosterone = "TT", SHBG = "SHBG", LH = "LH", FSH = "FSH",
  estradiol = "E2", progesterone = "Prog", free_T3 = "fT3",
  free_T4 = "fT4", aldosterone = "Aldo", renin = "Renin",
  insulin = "Ins", glucagon = "Gluc", GH = "GH", IGF1 = "IGF1",
  prolactin = "Prl", cortisol_0 = "Cort0", cortisol_30 = "Cort30"
)
hormone_markers(df, col_map = col_map)

Description

Implements a linear proxy for immunosenescence based on key inflammatory biomarkers, conceptually inspired by the inflammatory aging clock (iAge) literature. This simplified iAge is computed as a weighted sum of C-reactive protein (CRP), interleukin-6 (IL6), and tumor necrosis factor-alpha (TNFa).

Usage

iAge(
  data,
  col_map = NULL,
  weights = c(CRP = 0.33, IL6 = 0.33, TNFa = 0.34),
  verbose = TRUE,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  na_warn_prop = 0.2
)

Arguments

Details

By default, rows with any missing required marker return NA in the index (consistent with the default behavior of other package functions). Optional diagnostics can warn on high missingness and implausible negative values. Verbose mode prints step-by-step progress and a final summary.

Assumed units (no automatic unit conversion):

• CRP: mg/L

• IL6: pg/mL

• TNFa: pg/mL

Note:

• The original iAge model in Sayed et al. (Nature Aging, 2021) is a multi-marker machine learning model. This function provides a simple, linear proxy using three canonical inflammatory biomarkers. It is not identical to the original published iAge but is inspired by its rationale.

• This proxy is intended for exploratory feature engineering and cohort-level analyses. It must not be treated as a validated replacement for the published iAge model or used as a standalone clinical decision metric.

Value

A tibble with one column:

• iAge (numeric): the computed inflammatory age index.

References

Sayed N, others (2021). “An inflammatory aging clock (iAge) predicts multimorbidity, immunosenescence, frailty and cardiovascular aging.” Nature Aging, 1, 598–610. doi:10.1038/s43587-021-00082-y. (conceptual background; not method-identical to this implementation) Harris TB, Ferrucci L, Tracy RP, Corti MC, Wacholder S, Ettinger WH, Heimovitz H, Cohen HJ, Wallace R (1999). “Associations of Elevated Interleukin-6 and C-Reactive Protein Levels with Mortality in the Elderly.” The American Journal of Medicine, 106(5), 506–512. doi:10.1016/S0002-9343(99)00066-2. Bruunsgaard H, Ladelund S, Pedersen AN, Schroll M, Jorgensen T, Pedersen BK (2003). “Predicting death from tumour necrosis factor-alpha and interleukin-6 in 80-year-old people.” Clinical and Experimental Immunology, 132(1), 24–31. doi:10.1046/j.1365-2249.2003.02137.x.

See Also

impute_missing(), glycemic_markers()

Examples

library(tibble)
df <- tibble(
  CRP  = c(1.2, 3.5, NA),  # mg/L
  IL6  = c(2.0, 4.1, 1.5), # pg/mL
  TNFa = c(1.0, 1.8, 0.9)  # pg/mL
)
# Default behavior (rows with any missing marker return NA)
iAge(
  df,
  col_map = list(CRP = "CRP", IL6 = "IL6", TNFa = "TNFa")
)

# Keep NA if any marker missing in a row
iAge(
  df,
  col_map = list(CRP = "CRP", IL6 = "IL6", TNFa = "TNFa"),
  na_action = "keep"
)

# Verbose output
iAge(
  df,
  col_map = list(CRP = "CRP", IL6 = "IL6", TNFa = "TNFa"),
  verbose = TRUE
)

Description

Wraps mice to impute only numeric columns; non-numeric columns are untouched. Requires the mice package to be installed (Suggests). If no numeric columns contain NAs, data is returned unchanged.

Usage

impute_mice(data, m = 5, cols = NULL, verbose = FALSE, ...)

Arguments

Details

Notes:

• At least two numeric columns are typically needed by mice to borrow strength.

• This function runs m imputations and returns the first completed dataset.

• Messages from mice are suppressed; use verbose = TRUE here for high-level progress.

Value

A data.frame/tibble with numeric columns imputed by mice.

References

Rubin DB (1987). Multiple Imputation for Nonresponse in Surveys. Wiley. doi:10.1002/9780470316696. van Buuren S, Groothuis-Oudshoorn K (2011). “mice: Multivariate Imputation by Chained Equations in R.” Journal of Statistical Software, 45(3), 1–67. doi:10.18637/jss.v045.i03.

Examples

if (requireNamespace("mice", quietly = TRUE)) {
  df <- tibble::tibble(a = c(1, NA, 3), b = c(2, 4, NA), c = 5)
  impute_mice(df, m = 2, verbose = TRUE)
}

Description

Wraps missForest to impute numeric columns using non-parametric random forests. Requires the missForest package to be installed (Suggests). Non-numeric columns are untouched. If no numeric columns contain NAs, data is returned unchanged.

Usage

impute_missforest(data, ntree = 100, cols = NULL, verbose = FALSE, ...)

Arguments

Details

Notes:

• missForest uses iterative RF training; it can be slow on wide/high-NA data.

• Errors (e.g., insufficient unique values) are caught and a deterministic mean imputation fallback is applied to the selected numeric columns.

Value

A data.frame/tibble with numeric columns imputed by missForest (or mean fallback).

References

Stekhoven DJ, Buhlmann P (2012). “MissForest—non-parametric missing value imputation for mixed-type data.” Bioinformatics, 28(1), 112–118. doi:10.1093/bioinformatics/btr597.

Examples

if (requireNamespace("missForest", quietly = TRUE)) {
  df <- tibble::tibble(a = c(1, NA, 3), b = c(2, 4, NA), c = 5)
  impute_missforest(df, ntree = 50, verbose = TRUE)
}

Description

Performs deterministic, per-column imputation for numeric variables:

• "mean": replace NAs with the column mean

• "median": replace NAs with the column median

• "zero": replace NAs with 0

• "constant": replace NAs with the single value given in constant

Usage

impute_missing(
  data,
  method = c("mean", "median", "zero", "constant"),
  cols = NULL,
  constant = NULL,
  na_warn_prop = 0.2,
  verbose = FALSE
)

Arguments

Details

Non-numeric columns are left untouched. If cols = NULL, all numeric columns that have at least one NA are selected automatically. NA positions are the only values modified; non-NA entries are preserved as-is.

Quality checks:

• Warns for high-missingness columns (>= na_warn_prop).

• Warns and skips imputation when a column has no non-NA values (mean/median undefined).

• Coerces only numeric columns; non-numerics in cols are skipped with a warning.

Value

A data.frame/tibble of the same dimensions as data, with the specified columns' missing values imputed.

Examples

df <- tibble::tibble(a = c(1, NA, 3), b = c(NA, NA, 2), c = letters[1:3])
impute_missing(df, method = "mean")
impute_missing(df, method = "median", verbose = TRUE)
impute_missing(df, method = "constant", constant = -1, cols = "a")

Description

Panels:

• classic: NLR, PLR, LMR, dNLR, SII, SIRI, AISI, CRP_category

• eos: NLR, PLR, LMR, NER, SII, SIRI, PIV, CLR, CAR, PCR, mGPS, ESR (if mapped)

• both: union of classic and eos panels

Usage

inflammatory_markers(
  data,
  col_map = NULL,
  panel = c("auto", "classic", "eos", "both"),
  na_action = c("keep", "omit", "error"),
  verbose = TRUE
)

Arguments

Details

Derived markers:

• NLR = neutrophils / lymphocytes

• PLR = platelets / lymphocytes

• LMR = lymphocytes / monocytes

• dNLR = neutrophils / (WBC - neutrophils) when WBC available

• SII = platelets * neutrophils / lymphocytes

• SIRI = neutrophils * monocytes / lymphocytes

• AISI = neutrophils * monocytes * platelets / lymphocytes

• CRP_category: "low" (<1 mg/L), "moderate" (1-3 mg/L), "high" (>3 mg/L) when CRP available

• Eosinophil-panel extras: NER = neutrophils / eosinophils; PIV = platelets * neutrophils * monocytes / lymphocytes; CLR = CRP/lymphocytes; CAR = CRP/albumin; PCR = platelets/CRP; mGPS (CRP, albumin); ESR passthrough.

Note:

• These outputs are deterministic algebraic indices computed from the mapped laboratory variables. They are intended for feature engineering and descriptive analyses, not as standalone diagnosis/prognosis tools.

• References below document commonly used index definitions or interpretation conventions directly used in this implementation.

Value

tibble with selected inflammatory indices, with ID column prepended if detected (e.g. id, IID, participant_id).

References

Zahorec R (2001). “Ratio of neutrophil to lymphocyte counts–rapid and simple parameter of systemic inflammation and stress.” Bratislavske lekarske listy, 102(1), 5–14. No DOI identified; PMID: 11723675, https://pubmed.ncbi.nlm.nih.gov/11723675/. Hu B, others (2014). “Systemic Immune-Inflammation Index Predicts Prognosis of Patients after Curative Resection for Hepatocellular Carcinoma.” Clinical Cancer Research, 20(23), 6212–6222. doi:10.1158/1078-0432.CCR-14-0442. Qi Q, others (2016). “A novel systemic inflammation response index (SIRI) for predicting the survival of patients with pancreatic cancer after chemotherapy.” Cancer, 122(14), 2158–2167. doi:10.1002/cncr.30057. Proctor MJ, others (2011). “An inflammation-based prognostic score (mGPS) predicts cancer survival independent of tumour site: a Glasgow Inflammation Outcome Study.” British Journal of Cancer, 104(4), 726–734. doi:10.1038/sj.bjc.6606087. Pearson TA, others (2003). “Markers of inflammation and cardiovascular disease: a statement for healthcare professionals from the CDC and AHA.” Circulation, 107(3), 499–511. doi:10.1161/01.CIR.0000052939.59093.45.

Examples

# Quick smoke-test
df <- data.frame(neutrophils = 4, lymphocytes = 2, monocytes = 0.5,
                 platelets = 200, WBC = 7, CRP = 2.5)
inflammatory_markers(df, panel = "classic", na_action = "keep", verbose = FALSE)


df <- data.frame(
  neutrophils = c(4, 2),
  lymphocytes = c(2, 0),
  monocytes   = c(0.5, 0.3),
  platelets   = c(200, 150),
  WBC         = c(7, 4.5),
  CRP         = c(2.5, 0.8),
  albumin     = c(40, 42),
  eosinophils = c(0.2, 0.1),
  ESR         = c(12, 15)
)
cm <- list(
  neutrophils = "neutrophils", lymphocytes = "lymphocytes", monocytes = "monocytes",
  platelets = "platelets", WBC = "WBC", CRP = "CRP", albumin = "albumin",
  eosinophils = "eosinophils", ESR = "ESR"
)
classic_cm <- cm; classic_cm$eosinophils <- NULL; classic_cm$ESR <- NULL
inflammatory_markers(df, classic_cm, panel = "classic", na_action = "keep")
inflammatory_markers(df, cm, panel = "eos", na_action = "keep", verbose = TRUE)

Description

Insomnia Severity Index (ISI) scoring

Usage

isi_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "ISI",
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: ISI_total and ISI_severity (factor). Input columns are not included.

References

Bastien CH, Vallières A, Morin CM (2001). “Validation of the Insomnia Severity Index as an Outcome Measure for Insomnia Research.” Sleep Medicine, 2(4), 297–307. doi:10.1016/S1389-9457(00)00065-4.

Examples

df <- data.frame(isi_01 = 0, isi_02 = 1, isi_03 = 2, isi_04 = 1, isi_05 = 0, isi_06 = 1, isi_07 = 2)
isi_score(df)

Description

K10 scoring

Usage

k10_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "K10",
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: K10_total. Input columns are not included.

Note

K10 items are summed as provided. The original scale uses 1–5 coding (total 10–50); some implementations subtract 1 (0–4, total 0–40). The function accepts either coding, as no reverse-scored items are involved and min_val/max_val only affect reversal.

References

Kessler RC, Andrews G, Colpe LJ, Hiripi E, Mroczek DK, Normand ST, Walters EE, Zaslavsky AM (2002). “Short screening scales to monitor population prevalences and trends in non-specific psychological distress.” Psychological Medicine, 32(6), 959–976. doi:10.1017/S0033291702006074.

Examples

df <- data.frame(k10_01 = 0, k10_02 = 1, k10_03 = 2, k10_04 = 1, k10_05 = 0,
                 k10_06 = 1, k10_07 = 2, k10_08 = 1, k10_09 = 0, k10_10 = 1)
k10_score(df)

Description

K6 scoring

Usage

k6_score(
  data,
  col_map = list(),
  na_action = c("keep", "omit", "error"),
  missing_prop_max = 0.2,
  impute = c("none", "mean"),
  prefix = "K6",
  cutoff = 13,
  verbose = TRUE
)

Arguments

Value

A tibble of score columns only: K6_total and K6_case. Input columns are not included.

References

Kessler RC, Andrews G, Colpe LJ, Hiripi E, Mroczek DK, Normand ST, Walters EE, Zaslavsky AM (2002). “Short screening scales to monitor population prevalences and trends in non-specific psychological distress.” Psychological Medicine, 32(6), 959–976. doi:10.1017/S0033291702006074. Prochaska JJ, Sung H, Max W, Shi Y, Ong M (2012). “Validity Study of the K6 Scale as a Measure of Moderate Mental Distress Based on Mental Health Treatment Need and Utilization.” International Journal of Methods in Psychiatric Research, 21(2), 88–97. doi:10.1002/mpr.1349. (validation study)

Examples

df <- data.frame(k6_01 = 0, k6_02 = 1, k6_03 = 2, k6_04 = 1, k6_05 = 0, k6_06 = 1)
k6_score(df)

Description

Compute 2- and 5-year risk of end-stage kidney disease using the original 4-variable KFRE (Tangri et al., 2011) with optional data-quality diagnostics, and verbose progress reporting.

Usage

kidney_failure_risk(
  data,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR"),
  na_action = c("keep", "error", "omit", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

Details

This function preserves prior behavior by default:

• Inputs are taken as-is; NA values propagate to outputs (na_action = "keep").

• No capping or out-of-range checks are applied.

Units (no automatic conversion):

• age: years; sex: 1 = male, 2 = female

• eGFR: mL/min/1.73 m^2

• UACR: mg/g (albumin-to-creatinine ratio)

Details

• Prognostic index: ⁠PI = 0.220 x log(age) + (-0.556) x log(eGFR) + 0.451 x log(UACR) + 0.391 x (male)⁠ where male = 1 if sex == 1, else 0.

• Baseline survival: S0(2y) = 0.934, S0(5y) = 0.881 (Tangri 2011).

• Risks: KFRE_t = 1 - (S0_t ^ exp(PI)).

• The 2016 JAMA study provides a large, multinational validation of the KFRE in humans.

• This implementation computes the original 4-variable linear predictor and does not apply recalibration or alternative coefficient sets.

Value

A tibble with:

• KFRE_2yr risk (0-1) at 2 years

• KFRE_5yr risk (0-1) at 5 years

References

Tangri N, Stevens LA, Griffith J, others (2011). “A predictive model for progression of chronic kidney disease to kidney failure.” JAMA, 305(15), 1553–1559. doi:10.1001/jama.2011.451. Tangri N, Grams ME, Levey AS, others (2016). “Multinational assessment of accuracy of equations for predicting risk of kidney failure: a meta-analysis.” JAMA, 315(2), 164–174. doi:10.1001/jama.2015.18202.

See Also

inflammatory_markers(), iAge(), impute_missing()

Examples

library(tibble)
df <- tibble(
  age  = c(65, 72),
  sex  = c(1, 2),          # 1 = male, 2 = female
  eGFR = c(45, 22),        # mL/min/1.73 m^2
  UACR = c(300, 1200)      # mg/g
)
# Default behavior (NA propagate, no extreme checks)
kidney_failure_risk(
  data = df,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR")
)

# With verbose output

kidney_failure_risk(
  data = df,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR"),
  verbose = TRUE
)

Description

Computes the ratio of kynurenine to tryptophan, a marker of IDO activity and immune activation.

Usage

kyn_trp_ratio(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  verbose = TRUE
)

Arguments

Details

KTR is calculated as Kyn (nmol/L) divided by Trp (mumol/L). Elevated KTR indicates increased tryptophan catabolism via the kynurenine pathway, often reflecting inflammation and cell-mediated immune activation.

Inputs should already be in Kyn (nmol/L) and Trp (mumol/L).

Value

A tibble with one column: kyn_trp_ratio (numeric). If an ID column is detected, it is prepended.

References

Fuchs D, Moller AA, Reibnegger G, Werner ER, Werner-Felmayer G, Dierich MP, Wachter H (1998). “Serum kynurenine-to-tryptophan ratio increases with disease progression in HIV-1 infection.” Clinical Chemistry, 44(4), 858–862. doi:10.1093/clinchem/44.4.858. PMID:9555676.; Damerell V, Midttun O, Ulvik A, et al. (2025). “Circulating tryptophan-kynurenine pathway metabolites are associated with all-cause mortality among patients with stage I–III colorectal cancer.” International Journal of Cancer, 156(3), 552–565. doi:10.1002/ijc.35183. (clinical application in colorectal cancer)

Examples

# columns named exactly as the required keys (auto-detected)
df <- data.frame(kynurenine = c(2500, 3100, 2700), tryptophan = c(55, 48, 62))
kyn_trp_ratio(df, verbose = FALSE)

# non-standard column names require explicit col_map
df2 <- data.frame(Kyn_nM = c(2500, 3100, 2700), Trp_uM = c(55, 48, 62))
kyn_trp_ratio(df2, col_map = list(kynurenine = "Kyn_nM", tryptophan = "Trp_uM"),
             verbose = FALSE)

Description

Given total cholesterol, HDL, TG (and optionally LDL, ApoB/ApoA1, waist, BMI, glucose), computes:

• non_HDL_c, remnant_c

• ratio_TC_HDL, ratio_TG_HDL, ratio_LDL_HDL

• ApoB_ApoA1

• VAI_Men, VAI_Women

• LAP_Men, LAP_Women

• TyG_BMI

Usage

lipid_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

Details

Assumed units (no automatic conversion except where noted):

• TC, HDL_c, TG, LDL_c: mmol/L

• glucose: mmol/L (converted to mg/dL internally for TyG_BMI)

• waist: cm

• BMI: kg/m^2

Pre-computation (one level deep):

• If BMI is absent but weight (kg) and height (m or cm) are present, BMI is computed automatically.

• If glucose is absent but G0 is present (or vice versa), the alias is derived automatically.

• If LDL_c is absent, it is always estimated via Friedewald (TC - HDL - TG/2.2, mmol/L form). An informational message is emitted when verbose = TRUE.

Value

A tibble with computed lipid markers. Required outputs (always present): non_HDL_c, remnant_c, ratio_TC_HDL, ratio_TG_HDL, ratio_LDL_HDL, ApoB_ApoA1. Optional outputs (present when inputs available): VAI_Men, VAI_Women (waist + BMI required); LAP_Men, LAP_Women (waist required); TyG_BMI (BMI + glucose required). If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

References

Friedewald WT, Levy RI, Fredrickson DS (1972). “Estimation of the concentration of LDL cholesterol in plasma, without use of preparative ultracentrifuge.” Clinical Chemistry, 18(6), 499–502. doi:10.1093/clinchem/18.6.499. Amato MC, Giordano C, Galia M, Criscimanna A, Vitabile S, Midiri M, Galluzzo A (2010). “Visceral Adiposity Index: A Reliable Indicator of Visceral Fat Function Associated with Cardiometabolic Risk.” Diabetes Care, 33(4), 920–922. doi:10.2337/dc09-1825. Kahn HS (2005). “The Lipid Accumulation Product Performs Better than Body Mass Index as an Indicator of Cardiovascular Risk in Women.” BMC Cardiovascular Disorders, 5(1), 26. doi:10.1186/1471-2261-5-26. Er L, Wu S, Chou H, Hsu L, Teng M, Sun Y, Ko Y (2016). “Triglyceride Glucose-Body Mass Index Is a Simple and Clinically Useful Surrogate Marker for Insulin Resistance in Nondiabetic Individuals.” PLOS ONE, 11(3), e0149731. doi:10.1371/journal.pone.0149731. Khamseh ME, Malek M, Abbasi R, Taheri E, others (2021). “Triglyceride Glucose Index and Related Parameters (Triglyceride Glucose-Body Mass Index and Triglyceride Glucose-Waist Circumference) Identify Nonalcoholic Fatty Liver and Liver Fibrosis in Individuals with Overweight/Obesity.” Metabolic Syndrome and Related Disorders, 19(3), 167–173. doi:10.1089/met.2020.0109. (clinical application)

Examples

df <- data.frame(TC = c(5.2, 6.1), HDL_c = c(1.3, 1.1), TG = c(1.8, 2.3),
                 LDL_c = c(3.2, 4.1), waist = c(88, 95), BMI = c(26, 29))
# Full verbose output (default)
lipid_markers(df)
# Suppress messaging for batch use
lipid_markers(df, verbose = FALSE)
# Pre-compute BMI from weight and height
df2 <- data.frame(TC = 5.2, HDL_c = 1.3, TG = 1.8, weight = 70, height = 175)
lipid_markers(df2, verbose = FALSE)

Description

Computes:

• HSI = 8 * (ALT/AST) + BMI + 2 (if female) + 2 (if diabetes)

• NAFLD-LFS = -2.89 + 1.18MetS + 0.45Type2DM + 0.15Insulin_u + 0.04AST - 0.94*(AST/ALT)

Usage

liver_fat_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

Details

Assumptions/units:

• ALT, AST in U/L; BMI in kg/m^2.

• insulin is expected in muU/mL; if unavailable and I0 is provided, I0 is interpreted in pmol/L and converted to muU/mL via /6.

• MetS is taken directly if provided; otherwise derived using a simplified NCEP-ATP III style rule when sufficient inputs exist.

• Type2DM is taken from diabetes (logical or 0/1).

These scores are surrogate indices for research/feature-engineering use and are not validated as standalone clinical diagnostic tools.

Value

A tibble with columns HSI and NAFLD_LFS.

References

Lee J, Kim D, Kim HJ, Lee CH, Yang JI, Kim W, Kim YJ, Yoon J, Cho S, Sung M, Lee H (2010). “Hepatic steatosis index: a simple screening tool reflecting nonalcoholic fatty liver disease.” Digestive and Liver Disease, 42(7), 503–508. doi:10.1016/j.dld.2009.08.002. Kotronen A, Peltonen M, Hakkarainen A, Sevastianova K, Bergholm R, Johansson LM, Lundbom N, Rissanen A, Ridderstrale M, Groop L, Orho-Melander M, Yki-Järvinen H (2009). “Prediction of non-alcoholic fatty liver disease and liver fat using metabolic and genetic factors.” Gastroenterology, 137(3), 865–872. doi:10.1053/j.gastro.2009.06.005.