% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/renal_markers.R
\name{renal_markers}
\alias{renal_markers}
\title{Calculate a Suite of Renal Function, Injury, and Excretion Markers}
\usage{
renal_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 renal lab data.}

\item{col_map}{Named list mapping:
\itemize{
\item creatinine -> serum creatinine (mg/dL)
\item age -> age (years)
\item sex -> sex indicator (1 = male, 0 = female). Also accepts "male"/"female".
\item race -> race ("white", "black", or "other"). Also accepts common aliases.
\item BUN -> blood urea nitrogen (mg/dL)
\item optional cystatin_C -> serum cystatin C (mg/L)
\item optional urea_serum -> serum urea (mg/dL)
\item optional creatinine_urine -> urine creatinine (mg/dL)
\item optional urea_urine -> urine urea (mg/dL)
\item optional NGAL, KIM1, NAG, beta2_micro, IL18, L_FABP -> urine injury markers
}}

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

\item{na_warn_prop}{Proportion (0-1) threshold for high-missingness diagnostics.
Default 0.2.}

\item{verbose}{Logical; if \code{TRUE} (default), prints step-by-step progress
including column mapping, optional input availability, physiological range
information (informational only, values are not altered), the list of
markers being computed, and a per-column results summary.}
}
\value{
A tibble with computed renal markers:
\code{eGFR_cr}, \code{eGFR_cys}, \code{eGFR_combined}, \code{BUN_Cr_ratio}, \code{FE_Urea},
\code{NGAL}, \code{KIM1}, \code{NAG}, \code{Beta2Micro}, \code{IL18}, \code{L_FABP}.
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 routine blood and urine assays, \code{renal_markers()} computes:
\itemize{
\item eGFR_cr: CKD-EPI creatinine equation (2009 variant; race factor retained to preserve prior behavior)
\item eGFR_cys: CKD-EPI cystatin C equation (if \code{cystatin_C} provided)
\item eGFR_combined: CKD-EPI combined creatinine+cystatin C (if both provided)
\item BUN_Cr_ratio: Blood urea nitrogen / serum creatinine
\item FE_Urea: Fractional excretion of urea (\%)
\item NGAL, KIM1, NAG, Beta2Micro, IL18, L_FABP: pass-through urinary injury markers (if mapped)
}
}
\details{
Robust validation is applied, including NA handling (\code{na_action}), high-missingness
diagnostics, safe divisions with a consolidated zero-denominator warning, and an
optional input extremes scan/cap. New arguments are appended for backward compatibility.

Expected units (no automatic conversion performed):
\itemize{
\item creatinine (serum): mg/dL
\item cystatin C (serum): mg/L
\item BUN (serum): mg/dL
\item urea_serum, urea_urine: mg/dL
\item creatinine_urine: mg/dL
}
}
\note{
\code{eGFR_cr} uses the 2009 CKD-EPI creatinine equation (Levey et al. 2009) with the
Black-race multiplier (\eqn{\times 1.159}) retained. The 2021 race-free CKD-EPI
equations (Inker et al., NEJM 2021) are not yet implemented; the \code{race} input
is accepted for forward compatibility and used only for the 2009 race factor.
\code{eGFR_cys} and \code{eGFR_combined} use Inker et al. (2012); note that
\code{eGFR_combined} applies its own sex (\eqn{\times 1.008} female) and race
(\eqn{\times 1.145} Black) multipliers, which differ from those of \code{eGFR_cr}.
\code{NGAL}, \code{KIM1}, \code{NAG}, \code{Beta2Micro}, \code{IL18}, and \code{L_FABP} are
\strong{pass-through} columns — values are returned as-is with no formula applied.
}
\examples{
df <- tibble::tibble(Cr = 1.0, Age = 40, Sex = 1, Race = "white", BUN = 14)
cm <- list(creatinine = "Cr", age = "Age", sex = "Sex", race = "Race", BUN = "BUN")
renal_markers(df, cm)

}
\references{
\insertRef{levey2009ckdepi}{HealthMarkers}
\insertRef{inker2012cys}{HealthMarkers}
\insertRef{waikar2009feu}{HealthMarkers} (FE_Urea formula source; bib content: Kaplan and Kohn 1992)
\insertRef{parikh2011ngal}{HealthMarkers} (clinical context; NGAL is a pass-through biomarker)
\insertRef{vaidya2010kim1}{HealthMarkers} (KIM-1 biomarker qualification; pass-through)
\insertRef{portilla2008lfabp}{HealthMarkers} (L-FABP as AKI biomarker; pass-through)
}
