% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kidney_kfre.R
\name{kidney_failure_risk}
\alias{kidney_failure_risk}
\title{Kidney Failure Risk Equation (KFRE, 2- and 5-year risk)}
\usage{
kidney_failure_risk(
  data,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR"),
  na_action = c("keep", "error", "omit", "warn"),
  na_warn_prop = 0.2,
  verbose = TRUE
)
}
\arguments{
\item{data}{A data.frame or tibble containing at least the columns mapped in \code{col_map}.}

\item{col_map}{Named list mapping:
\itemize{
\item \code{age}  -> age in years
\item \code{sex}  -> sex code (1 = male, 2 = female)
\item \code{eGFR} -> estimated GFR (mL/min/1.73 m^2)
\item \code{UACR} -> urine albumin-to-creatinine ratio (mg/g)
}}

\item{na_action}{One of c("keep","error","omit","warn"). Default "keep" to preserve previous behavior:
\itemize{
\item "keep": propagate NA/NaN through logs and outputs.
\item "error": abort if any required input contains missing values.
\item "omit": drop rows with NA in required inputs before computation.
\item "warn": like "keep" but emits high-missingness warnings.
}}

\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 stepwise messages and a completion summary. Default TRUE.}
}
\value{
A tibble with:
\itemize{
\item \code{KFRE_2yr} risk (0-1) at 2 years
\item \code{KFRE_5yr} risk (0-1) at 5 years
}
}
\description{
Compute 2- and 5-year risk of end-stage kidney disease using the original
4-variable KFRE (Tangri et al., 2011) with optional data-quality diagnostics,
and verbose progress reporting.
}
\details{
This function preserves prior behavior by default:
\itemize{
\item Inputs are taken as-is; NA values propagate to outputs (na_action = "keep").
\item No capping or out-of-range checks are applied.
}

Units (no automatic conversion):
\itemize{
\item age: years; sex: 1 = male, 2 = female
\item eGFR: mL/min/1.73 m^2
\item UACR: mg/g (albumin-to-creatinine ratio)
}

Details
\itemize{
\item Prognostic index: \verb{PI = 0.220 x log(age) + (-0.556) x log(eGFR) + 0.451 x log(UACR) + 0.391 x (male)}
where male = 1 if sex == 1, else 0.
\item Baseline survival: S0(2y) = 0.934, S0(5y) = 0.881 (Tangri 2011).
\item Risks: KFRE_t = 1 - (S0_t ^ exp(PI)).
\item The 2016 JAMA study provides a large, multinational validation of the KFRE in humans.
\item This implementation computes the original 4-variable linear predictor and does not
apply recalibration or alternative coefficient sets.
}
}
\examples{
library(tibble)
df <- tibble(
  age  = c(65, 72),
  sex  = c(1, 2),          # 1 = male, 2 = female
  eGFR = c(45, 22),        # mL/min/1.73 m^2
  UACR = c(300, 1200)      # mg/g
)
# Default behavior (NA propagate, no extreme checks)
kidney_failure_risk(
  data = df,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR")
)

# With verbose output
\donttest{
kidney_failure_risk(
  data = df,
  col_map = list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR"),
  verbose = TRUE
)
}

}
\references{
\insertRef{tangri2011kfre}{HealthMarkers}
\insertRef{tangri2016meta}{HealthMarkers}
}
\seealso{
\code{\link[=inflammatory_markers]{inflammatory_markers()}}, \code{\link[=iAge]{iAge()}}, \code{\link[=impute_missing]{impute_missing()}}
}
