% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/glycemic_markers.R
\name{glycemic_markers}
\alias{glycemic_markers}
\title{Calculate glycemic-, C-peptide-, and additional metabolic markers}
\usage{
glycemic_markers(
  data,
  col_map = NULL,
  na_action = c("ignore", "warn", "error", "keep", "omit"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or tibble containing at least:
\itemize{
\item HDL_c (mmol/L), TG (mmol/L), BMI (kg/m^2)
Optional if present: glucose (mmol/L), HbA1c (mmol/mol), C_peptide (pmol/L),
G0 (mmol/L), I0 (pmol/L), leptin (ng/mL), adiponectin (ng/mL).
}}

\item{col_map}{Optional named list mapping keys to column names in \code{data}.
Required keys: \code{HDL_c}, \code{TG}, \code{BMI}. Optional keys (if present will be used):
\code{glucose}, \code{HbA1c}, \code{C_peptide}, \code{G0}, \code{I0}, \code{leptin}, \code{adiponectin}.
If \code{NULL} (default), the function uses columns named exactly as the keys.}

\item{na_action}{One of \code{c("ignore","warn","error","keep","omit")}.
HM-CS aliases: \code{keep} == \code{ignore}; \code{omit} drops rows with any NA/non-finite
in used inputs before computing markers. Default "ignore".}

\item{na_warn_prop}{Proportion (0-1) threshold for high-missingness warnings
among used columns when \code{na_action = "warn"}. Default 0.2.}

\item{verbose}{Logical; if \code{TRUE} (default), prints step-by-step progress
including column mapping, optional input availability, pre-computation
notes, physiological range information (informational only, values are not
altered), the list of markers being computed with their inputs, and a
per-column results summary.}
}
\value{
A tibble with columns:
\itemize{
\item SPISE, METS_IR, prediabetes, diabetes, HOMA_CP, LAR, ASI, TyG_index
If an ID column is detected in \code{data} (e.g. \code{id}, \code{IID}, \code{participant_id}),
it is prepended as the first output column.
}
}
\description{
Given fasting labs and anthropometry, computes:
\itemize{
\item SPISE (Single-Point Insulin Sensitivity Estimator)
\item METS_IR (Metabolic Score for Insulin Resistance)
\item prediabetes flag (HbA1c >= 42 mmol/mol)
\item diabetes flag (HbA1c >= 48 mmol/mol)
\item HOMA_CP (C-peptide-based HOMA-IR variant; operational formula, see notes)
\item LAR (Leptin/Adiponectin Ratio)
\item ASI (Adiponectin Sensitivity Index; adiponectin/insulin)
\item TyG_index (Triglyceride-Glucose Index)
}
}
\details{
Assumed units (no automatic conversion of inputs except where noted):
\itemize{
\item HDL_c, TG: mmol/L (TyG internally converts TG to mg/dL via 88.57)
\item BMI: kg/m^2
\item glucose, G0: mmol/L (TyG internally converts glucose to mg/dL via 18)
\item HbA1c: mmol/mol
\item C_peptide, I0: pmol/L (HOMA_CP uses I-like conversion factor 6 as in insulin muU/mL; see notes)
\item 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:
\itemize{
\item Input validation ensures required variables exist and are numeric-coercible.
\item Non-numeric inputs are coerced to numeric with a warning (NAs introduced reported).
\item Missing or non-finite inputs are handled via \code{na_action}.
\item Logs and divisions are computed safely (non-positive arguments yield NA).
\item Physiological range notes are printed when \code{verbose = TRUE} (values are not altered).
\item Verbose mode prints step-by-step progress and a completion summary.
}

Optional marker detection and pre-computation (one level deep):
When \code{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 \code{data}. If \code{BMI} is absent
but \code{weight} (kg) and \code{height} (m or cm) are present, BMI is computed
automatically. If \code{glucose} is absent but \code{G0} column exists (or vice
versa), the missing key is derived via alias. With \code{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:
\itemize{
\item 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).
}
}
\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)

\donttest{
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)
}
}
\references{
\insertRef{paulmichl2016spise}{HealthMarkers}
\insertRef{bellogaytan2018metsir}{HealthMarkers}
\insertRef{fruhbeck2018adiponectinleptin}{HealthMarkers}
\insertRef{matthews1985homa}{HealthMarkers}
\insertRef{simentalmendia2008tyg}{HealthMarkers}
\insertRef{yang2006adiponectininsulin}{HealthMarkers}
}
