% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/urine_markers.R
\name{urine_markers}
\alias{urine_markers}
\title{Calculate urine-only renal and tubular markers (research-ready)}
\usage{
urine_markers(
  data,
  col_map = NULL,
  verbose = TRUE,
  na_action = c("keep", "omit", "error"),
  na_warn_prop = 0.2
)
}
\arguments{
\item{data}{A data.frame or tibble with at least urine_albumin and urine_creatinine.}

\item{col_map}{Optional named list mapping canonical keys (e.g., \code{urine_albumin},
\code{urine_creatinine}) to actual column names in \code{data}. If \code{NULL}, column names
are inferred automatically.}

\item{verbose}{Logical; if \code{TRUE}, prints progress messages and a completion summary. Default FALSE.}

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

\item{na_warn_prop}{Proportion \eqn{[0,1]} to trigger high-missingness warnings for required inputs. Default 0.2.}
}
\value{
A tibble with columns:
UACR, albuminuria_stage, microalbuminuria, UPCR, U_Na_K_ratio,
NGAL_per_gCr, KIM1_per_gCr, NAG_per_gCr, Beta2Micro_per_gCr,
A1Micro_per_gCr, IL18_per_gCr, L_FABP_per_gCr
}
\description{
Computes (urine-only):
\itemize{
\item UACR (Albumin-to-Creatinine Ratio, mg/g)
\item albuminuria_stage (KDIGO A1/A2/A3 by UACR)
\item microalbuminuria flag ("normal" vs "micro")
\item UPCR (Urine Protein-to-Creatinine Ratio, mg/g; if urine_protein available)
\item U_Na_K_ratio (urine Na+/K+; if urine_Na and urine_K available)
\item Creatinine-normalized tubular markers (if present, per g creatinine):
NGAL_per_gCr, KIM1_per_gCr, NAG_per_gCr, Beta2Micro_per_gCr,
A1Micro_per_gCr, IL18_per_gCr, L_FABP_per_gCr
}
}
\details{
Inputs are validated, missingness handled via \code{na_action}, divisions are
safeguarded (Inf/NaN -> NA) with a consolidated zero-denominator warning,
and an optional extremes scan/cap is available.

Expected units:
\itemize{
\item urine_albumin: mg/L
\item urine_protein: mg/L (optional)
\item urine_creatinine: mg/dL
\item urine_Na, urine_K: mmol/L (optional)
\item Optional tubular markers above assumed mg/L when normalized per g creatinine
}
}
\note{
UACR formula: albumin (mg/L) / creatinine (g/L) = albumin (mg/L) \eqn{\times} 100 /
creatinine (mg/dL). UPCR and per-gCr tubular markers use the same creatinine
denominator: \verb{gCr_den = creatinine (mg/dL) \\times 0.01} (= g/L).
Tubular markers (NGAL, KIM-1, NAG, Beta-2-microglobulin, alpha-1-microglobulin,
IL-18, L-FABP) are \strong{pass-through} columns normalised per g creatinine; no
formula other than creatinine adjustment is applied.
}
\examples{
df <- tibble::tibble(
  urine_albumin    = 30,
  urine_creatinine = 1.2,
  serum_creatinine = 0.9,
  plasma_Na        = 140,
  urine_Na         = 100,
  age              = 55,
  sex              = 2,
  urine_protein    = 150
)
urine_markers(df)
}
\references{
\insertRef{mogensen1984uacr}{HealthMarkers}
\insertRef{ginsberg1983upcr}{HealthMarkers}
\insertRef{kdigo2012ckd}{HealthMarkers} (albuminuria staging A1–A3 UACR cutoffs)
\insertRef{dezeeuw2006uacr}{HealthMarkers} (prognostic UACR validation; background)
\insertRef{ichimura2004kim1}{HealthMarkers} (KIM-1 tubular biomarker; pass-through normalization, background)
\insertRef{portilla2008lfabp}{HealthMarkers} (L-FABP tubular biomarker; pass-through normalization, background)
}
