% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nutrient_markers.R
\name{nutrient_markers}
\alias{nutrient_markers}
\title{Compute a Suite of Nutrient-Based Health Markers}
\usage{
nutrient_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data frame or tibble containing subject-level data.}

\item{col_map}{Optional named list mapping variable keys (see Details) to
column names in \code{data}. You only need to supply the keys you have; any
markers with missing inputs return \code{NA}. If NULL, defaults to identity
mapping for all known keys.}

\item{na_action}{One of c("keep","omit","error") controlling missing-data policy
across the columns referenced by \code{col_map}.
\itemize{
\item "keep" (default): keep NA; outputs become NA where inputs are NA.
\item "omit": drop rows with NA in any used input column.
\item "error": abort if any used input contains NA.
}}

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

\item{verbose}{Logical; if TRUE, prints stepwise messages and a final summary via hm_inform. Default FALSE.}
}
\value{
A tibble with one row per input row and these columns:
FerritinTS, AGR, Omega3Index, Mg_Cr_Ratio, GlycatedAlbuminPct,
UA_Cr_Ratio, BUN_Cr_Ratio, Ca_x_Phosphate, AnionGap, Tyr_Phe_Ratio.
}
\description{
Given a data frame or tibble of routine biochemical labs,
\code{nutrient_markers()} returns a set of widely used ratios, products,
and simple percentages that summarize iron metabolism, protein status,
omega-3 balance, renal excretion, mineral homeostasis, and aromatic
amino-acid patterns.
}
\details{
Recognized markers (returned as columns):
\itemize{
\item FerritinTS: Ferritin / Transferrin saturation
\item AGR: Albumin / Globulin, where Globulin = Total protein - Albumin
\item Omega3Index: EPA + DHA (percentage points)
\item Mg_Cr_Ratio: Magnesium / Creatinine
\item GlycatedAlbuminPct: (Glycated albumin / Albumin) x 100
\item UA_Cr_Ratio: Uric acid / Creatinine
\item BUN_Cr_Ratio: BUN / Creatinine
\item Ca_x_Phosphate: Calcium x Phosphate
\item AnionGap: (Na + K) - (Cl + HCO3)
\item Tyr_Phe_Ratio: Tyrosine / Phenylalanine
}

Recognized \code{col_map} keys and expected units (no automatic conversion):
\itemize{
\item ferritin: Serum ferritin (ng/mL)
\item transferrin_sat: Transferrin saturation (\%)
\item albumin: Serum albumin (g/L)
\item total_protein: Total serum protein (g/L)
\item EPA: Red-cell EPA as \% of total fatty acids
\item DHA: Red-cell DHA as \% of total fatty acids
\item Mg: Serum magnesium (mmol/L)
\item creatinine: Serum creatinine (umol/L)
\item glycated_albumin: Glycated albumin (g/L)
\item uric_acid: Serum uric acid (umol/L)
\item BUN: Blood urea nitrogen (mg/dL)
\item phosphate: Serum phosphate (mmol/L)
\item calcium: Serum calcium (mmol/L)
\item Na: Serum sodium (mmol/L)
\item K: Serum potassium (mmol/L)
\item Cl: Serum chloride (mmol/L)
\item HCO3: Serum bicarbonate (mmol/L)
\item Tyr: Serum tyrosine (umol/L)
\item Phe: Serum phenylalanine (umol/L)
}

\strong{Unit-mixing notes:}
\itemize{
\item \code{BUN_Cr_Ratio} divides BUN (mg/dL) by creatinine (umol/L). This is NOT
numerically equivalent to the standard clinical BUN:Creatinine ratio
(reference range ~10-20), which requires both in mg/dL. The result here
is approximately 88.4x smaller than the standard ratio. Provide creatinine
in mg/dL and adjust \code{col_map} if you require the standard clinical ratio.
\item \code{Mg_Cr_Ratio} divides Mg (mmol/L) by creatinine (umol/L). The result is
1/1000 of the standard Mg/Cr ratio in mmol/mmol. Typically applied to urine;
serum Mg/Cr is not a standard clinical metric.
}

Default \code{extreme_rules} (inputs) are broad and intended for unit/entry checks:
ferritin (0, 2000), transferrin_sat (0, 100), albumin (10, 60), total_protein (40, 100),
EPA (0, 20), DHA (0, 20), Mg (0.2, 3), creatinine (20, 2000), glycated_albumin (0, 60),
uric_acid (50, 1000), BUN (1, 150), phosphate (0.1, 5), calcium (0.5, 4),
Na (100, 200), K (2, 8), Cl (70, 130), HCO3 (5, 45), Tyr (10, 300), Phe (20, 300).
}
\examples{
# Quick smoke-test
df <- data.frame(ferritin = 50, albumin = 45, uric_acid = 300, Na = 140)
nutrient_markers(df, verbose = FALSE)

\donttest{
df <- tibble::tibble(
  ferritin         = c(50, 100),
  transferrin_sat  = c(30, 50),
  albumin          = c(45, 40),
  total_protein    = c(70, 75),
  EPA              = c(2.0, 2.5),
  DHA              = c(4.0, 4.5),
  Mg               = c(0.85, 0.90),
  creatinine       = c(80, 90),
  glycated_albumin = c(12, 14),
  uric_acid        = c(300, 400),
  BUN              = c(14, 16),
  phosphate        = c(1.0, 1.2),
  calcium          = c(2.3, 2.4),
  Na               = c(140, 138),
  K                = c(4.2, 4.0),
  Cl               = c(100, 102),
  HCO3             = c(24, 26),
  Tyr              = c(60, 70),
  Phe              = c(50, 55)
)
nutrient_markers(df, verbose = TRUE)
}

}
\references{
\insertRef{harris2004omega3}{HealthMarkers}
\insertRef{koga2010glyalb}{HealthMarkers}
\insertRef{block1998calcp}{HealthMarkers}
\insertRef{waikar2009creak}{HealthMarkers} (creatinine kinetics context)
}
