% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/metabolic_risk_features.R
\name{metabolic_risk_features}
\alias{metabolic_risk_features}
\title{Calculate metabolic risk feature flags (pediatric-friendly thresholds)}
\usage{
metabolic_risk_features(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error", "ignore", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or tibble containing at least these numeric columns:
\itemize{
\item chol_total, chol_ldl, chol_hdl, triglycerides (mmol/L)
\item age_year (years)
\item z_HOMA (standardized HOMA-IR)
\item glucose (mmol/L)
\item HbA1c (mmol/mol; IFCC units)
\item bp_sys_z, bp_dia_z (BP z-scores)
}}

\item{col_map}{Optional named list to map required keys to column names in \code{data}.
Keys: c("chol_total","chol_ldl","chol_hdl","triglycerides","age_year",
"z_HOMA","glucose","HbA1c","bp_sys_z","bp_dia_z"). Default NULL (use same names).}

\item{na_action}{One of c("keep","omit","error","ignore","warn") controlling missing-data policy.
\itemize{
\item "keep": keep NA; outputs become NA where inputs are NA.
\item "omit": drop rows with NA in any required input.
\item "error": abort if any required input contains NA.
\item "ignore"/"warn": aliases of "keep"; "warn" also emits missingness diagnostics.
}}

\item{na_warn_prop}{Numeric in \eqn{[0,1]}; per-variable threshold for high-missingness warnings. Default 0.2.}

\item{verbose}{Logical; if TRUE, prints column mapping and computing messages.}
}
\value{
A tibble with four factor columns (levels c("0","1")):
\itemize{
\item dyslipidemia
\item insulin_resistance
\item hyperglycemia
\item hypertension
}
}
\description{
Compute four binary risk flags from routine clinical measures:
\itemize{
\item dyslipidemia
\item insulin_resistance
\item hyperglycemia (prediabetes-range glycemia)
\item hypertension (BP >=95th percentile via z > 1.64)
}
}
\details{
By default, behavior matches prior implementation: required columns are
validated, NA values are kept (propagate to outputs), no extreme-value
checks or capping are applied, and a tibble with 0/1 factor flags is returned.

Units and criteria (no automatic unit conversion):
\itemize{
\item Lipids (mmol/L): total cholesterol > 5.2 OR LDL-C > 3.4 OR HDL-C < 1.0 OR
triglycerides > 1.1 (age 0-9) OR > 1.5 (age 10-19) => dyslipidemia = 1.
Note: no TG cutoff is applied for adults aged >= 20 years.
\item Insulin resistance: z_HOMA > 1.28 (~=90th percentile) => insulin_resistance = 1.
z_HOMA is a within-sample or external z-score of HOMA-IR (see Matthews et al. 1985).
\item Hyperglycemia: fasting glucose in (5.6, 6.9) mmol/L OR HbA1c in (39, 47) mmol/mol
=> hyperglycemia = 1. Boundaries are EXCLUSIVE (open intervals); boundary values
(exactly 5.6 or 6.9 mmol/L; exactly 39 or 47 mmol/mol) are not flagged.
ADA criteria use inclusive lower bound (>= 5.6 mmol/L, >= 39 mmol/mol).
\item Hypertension: either BP z-score > 1.64 (~=95th percentile) for systolic or diastolic
=> hypertension = 1.
}
}
\note{
These flags are heuristic screening rules derived from published clinical
guidelines. They are not validated diagnostic criteria and should not replace
clinical judgment. The dyslipidemia and hypertension thresholds are designed
for pediatric populations (ages 0-19); for adults >= 20, only TC, LDL-C, and
HDL-C criteria contribute to the dyslipidemia flag.
}
\examples{
df <- data.frame(
  chol_total = c(5.2, 6.4), chol_ldl = c(3.2, 4.1), chol_hdl = c(1.3, 1.0),
  triglycerides = c(1.8, 2.5), age_year = c(45, 60), z_HOMA = c(0.5, 1.2),
  glucose = c(5.5, 6.8), HbA1c = c(38, 46), bp_sys_z = c(0.2, 1.1),
  bp_dia_z = c(0.1, 0.9)
)
metabolic_risk_features(df)
}
\references{
\insertRef{nhlbi2011lipids}{HealthMarkers}
\insertRef{ada2024standards}{HealthMarkers}
\insertRef{flynn2017bp}{HealthMarkers}
\insertRef{matthews1985homa}{HealthMarkers}
}
\seealso{
\code{\link[=liver_markers]{liver_markers()}}, \code{\link[=lipid_markers]{lipid_markers()}}, \code{\link[=kidney_failure_risk]{kidney_failure_risk()}}, \code{\link[=inflammatory_markers]{inflammatory_markers()}}
}
