% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lipid_markers.R
\name{lipid_markers}
\alias{lipid_markers}
\title{Calculate lipid-panel markers, Visceral Adiposity Index (VAI),
Lipid Accumulation Product (LAP), and TyG-BMI index}
\usage{
lipid_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A \code{data.frame} or \code{tibble} containing your lipid
(and optional anthropometry/glucose) data.}

\item{col_map}{Named list mapping:
\itemize{
\item \code{TC}    -> total cholesterol
\item \code{HDL_c} -> HDL-C
\item \code{TG}    -> triglycerides
\item \code{LDL_c} -> (optional) LDL-C; if absent, estimated via Friedewald
\item \code{ApoB}, \code{ApoA1} -> (optional) apolipoproteins
\item \code{waist} -> (optional) waist circumference (cm)
\item \code{BMI}   -> (optional) body mass index (kg/m^2)
\item \code{glucose} -> (optional) fasting glucose (mmol/L); used for TyG_BMI
}}

\item{na_action}{One of \code{c("keep","omit","error","ignore","warn")}.
\itemize{
\item keep/ignore: compute and propagate NA in outputs
\item omit: drop rows with NA in required inputs (TC, HDL_c, TG)
\item error: abort if any required input contains NA
\item warn: like keep, but emit missingness warnings
}}

\item{na_warn_prop}{Proportion (0-1) threshold for high-missingness
warnings 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 computed lipid markers.
Required outputs (always present):
\code{non_HDL_c}, \code{remnant_c}, \code{ratio_TC_HDL}, \code{ratio_TG_HDL},
\code{ratio_LDL_HDL}, \code{ApoB_ApoA1}.
Optional outputs (present when inputs available):
\code{VAI_Men}, \code{VAI_Women} (waist + BMI required);
\code{LAP_Men}, \code{LAP_Women} (waist required);
\code{TyG_BMI} (BMI + glucose required).
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 total cholesterol, HDL, TG (and optionally LDL, ApoB/ApoA1,
waist, BMI, glucose), computes:
\itemize{
\item \code{non_HDL_c}, \code{remnant_c}
\item \code{ratio_TC_HDL}, \code{ratio_TG_HDL}, \code{ratio_LDL_HDL}
\item \code{ApoB_ApoA1}
\item \code{VAI_Men}, \code{VAI_Women}
\item \code{LAP_Men}, \code{LAP_Women}
\item \code{TyG_BMI}
}
}
\details{
Assumed units (no automatic conversion except where noted):
\itemize{
\item TC, HDL_c, TG, LDL_c: mmol/L
\item glucose: mmol/L (converted to mg/dL internally for TyG_BMI)
\item waist: cm
\item BMI: kg/m^2
}

Pre-computation (one level deep):
\itemize{
\item If \code{BMI} is absent but \code{weight} (kg) and \code{height} (m or cm) are
present, BMI is computed automatically.
\item If \code{glucose} is absent but \code{G0} is present (or vice versa), the alias
is derived automatically.
\item If \code{LDL_c} is absent, it is always estimated via Friedewald
(TC - HDL - TG/2.2, mmol/L form). An informational message is emitted when
\code{verbose = TRUE}.
}
}
\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)
}
\references{
\insertRef{friedewald1972}{HealthMarkers}
\insertRef{amato2010vai}{HealthMarkers}
\insertRef{kahn2005lap}{HealthMarkers}
\insertRef{lee2016tyg}{HealthMarkers}
\insertRef{lee2020tygbmi}{HealthMarkers} (clinical application)
}
