% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vitamin_markers.R
\name{vitamin_markers}
\alias{vitamin_markers}
\title{Compute composite vitamin and endocrine marker ratios and z-scores}
\usage{
vitamin_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 with vitamin/analyte columns.}

\item{col_map}{Named list mapping required keys to column names:
VitD, VitD_ref_mean, VitD_ref_sd, B12, Folate, Ferritin, TSat,
Cortisol, DHEAS, Testosterone, Estradiol, TSH, free_T4,
Retinol, Retinol_ref_mean, Retinol_ref_sd, Tocopherol, Total_lipids,
PIVKA_II, VitC, Homocysteine, MMA, Magnesium, Zinc, Copper.}

\item{na_action}{One of c("keep","omit","error") for required inputs. Default "keep".}

\item{na_warn_prop}{Proportion \eqn{[0,1]} to trigger high-missingness debug notices. Default 0.2.}

\item{verbose}{Logical; if \code{TRUE} (default), prints column mapping, input
availability, physiological range information (informational only, values
not altered), the list of markers being computed with their inputs, and a
per-column results summary.}
}
\value{
A tibble with columns:
VitD_Z, B12_Fol_Ratio, Ferr_TSat_R, Cort_DHEA_R, T_E2_Ratio, TSH_fT4_R,
Retinol_Z, Toco_Lip_R, PIVKA_II, VitC, Homocysteine, MMA, Mg_Zn_R, Cu_Zn_R.
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 serum/plasma vitamins and related analytes, \code{vitamin_markers()} computes:
\itemize{
\item VitD_Z: z-score of 25(OH)D using provided reference mean/sd
\item B12_Fol_Ratio: vitamin B12 / folate
\item Ferr_TSat_R: ferritin / transferrin saturation (TSat)
\item Cort_DHEA_R: cortisol / DHEA-S
\item T_E2_Ratio: testosterone / estradiol
\item TSH_fT4_R: TSH / free T4
\item Retinol_Z: z-score of retinol using provided reference mean/sd
\item Toco_Lip_R: alpha-tocopherol / total lipids
\item Mg_Zn_R: magnesium / zinc
\item Cu_Zn_R: copper / zinc
Plus pass-through: PIVKA_II, VitC, Homocysteine, MMA
}
}
\details{
HM-CS v2:
\itemize{
\item Validation via \code{hm_validate_inputs(data, col_map, required_keys, fn)}
\item User errors via \code{rlang::abort(..., class=...)}
\item Verbosity via \code{hm_inform(level)} controlled by \code{options(healthmarkers.verbose)}
\item High-missingness diagnostics at debug level only
}
}
\note{
\code{VitD_Z} and \code{Retinol_Z} are z-scores using \strong{user-supplied} reference
mean and SD; no population reference equations are applied. All ratio markers
(\code{B12_Fol_Ratio}, \code{Ferr_TSat_R}, \code{Cort_DHEA_R}, \code{T_E2_Ratio}, \code{TSH_fT4_R},
\code{Toco_Lip_R}, \code{Mg_Zn_R}, \code{Cu_Zn_R}) are simple numerator/denominator
divisions. \code{PIVKA_II}, \code{VitC}, \code{Homocysteine}, and \code{MMA} are
\strong{pass-through} columns; no formula is applied.
}
\examples{
\donttest{
# All 25 required columns must be supplied
df <- data.frame(
  VitD = 50, VitD_ref_mean = 40, VitD_ref_sd = 5,
  B12 = 300, Folate = 15, Ferritin = 80, TSat = 0.25,
  Cortisol = 200, DHEAS = 100, Testosterone = 12, Estradiol = 120,
  TSH = 2, free_T4 = 14, Retinol = 0.8, Retinol_ref_mean = 0.9,
  Retinol_ref_sd = 0.2, Tocopherol = 30, Total_lipids = 3,
  PIVKA_II = 5, VitC = 60, Homocysteine = 10, MMA = 0.3,
  Magnesium = 0.8, Zinc = 15, Copper = 15
)
vitamin_markers(df, verbose = FALSE)
}

}
\references{
\insertRef{holick2007vitddeficiency}{HealthMarkers} (vitamin D deficiency review; background)
\insertRef{oleary2010vitb12}{HealthMarkers} (vitamin B12 in health and disease; background)
\insertRef{ganz2015iron}{HealthMarkers} (iron homeostasis and ferritin; background)
}
