Calculate a Suite of Renal Function, Injury, and Excretion Markers

Given routine blood and urine assays, renal_markers() computes:

eGFR_cr: CKD-EPI creatinine equation (2009 variant; race factor retained to preserve prior behavior)
eGFR_cys: CKD-EPI cystatin C equation (if cystatin_C provided)
eGFR_combined: CKD-EPI combined creatinine+cystatin C (if both provided)
BUN_Cr_ratio: Blood urea nitrogen / serum creatinine
FE_Urea: Fractional excretion of urea (%)
NGAL, KIM1, NAG, Beta2Micro, IL18, L_FABP: pass-through urinary injury markers (if mapped)

Usage

renal_markers(
  data,
  col_map = NULL,
  na_action = c("keep", "omit", "error"),
  na_warn_prop = 0.2,
  verbose = TRUE
)

Arguments

data

A data.frame or tibble with renal lab data.

col_map

Named list mapping:

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

na_action

One of c("keep","omit","error") for handling missing values in required inputs. Default "keep".

na_warn_prop

Proportion (0-1) threshold for high-missingness diagnostics. Default 0.2.

verbose

Logical; if 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: eGFR_cr, eGFR_cys, eGFR_combined, BUN_Cr_ratio, FE_Urea, NGAL, KIM1, NAG, Beta2Micro, IL18, L_FABP. If an ID column is detected in data (e.g. id, IID, participant_id), it is prepended as the first output column.

Details

Robust validation is applied, including NA handling (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):

creatinine (serum): mg/dL
cystatin C (serum): mg/L
BUN (serum): mg/dL
urea_serum, urea_urine: mg/dL
creatinine_urine: mg/dL

Note

eGFR_cr uses the 2009 CKD-EPI creatinine equation (Levey et al. 2009) with the Black-race multiplier (\(\times 1.159\)) retained. The 2021 race-free CKD-EPI equations (Inker et al., NEJM 2021) are not yet implemented; the race input is accepted for forward compatibility and used only for the 2009 race factor. eGFR_cys and eGFR_combined use Inker et al. (2012); note that eGFR_combined applies its own sex (\(\times 1.008\) female) and race (\(\times 1.145\) Black) multipliers, which differ from those of eGFR_cr. NGAL, KIM1, NAG, Beta2Micro, IL18, and L_FABP are pass-through columns — values are returned as-is with no formula applied.

References

Levey AS, Stevens LA, Schmid CH, others (2009). “A new equation to estimate glomerular filtration rate.” Annals of Internal Medicine, 150(9), 604–612. doi:10.7326/0003-4819-150-9-200905050-00006 . Inker LA, Schmid CH, Tighiouart H, others (2012). “Estimating glomerular filtration rate from serum cystatin C.” New England Journal of Medicine, 367(1), 20–29. doi:10.1056/NEJMoa1114248 . Kaplan AA, Kohn OF (1992). “Fractional Excretion of Urea as a Guide to Renal Dysfunction.” American Journal of Nephrology, 12(1–2), 49–54. doi:10.1159/000168417 . (FE_Urea formula source; bib content: Kaplan and Kohn 1992) Parikh CR, Coca SG, Thiessen-Philbrook H, others (2011). “Postoperative Biomarkers Predict Acute Kidney Injury and Poor Outcomes after Adult Cardiac Surgery.” Journal of the American Society of Nephrology, 22(12), 1737–1747. doi:10.1681/ASN.2010121302 . (clinical context; NGAL is a pass-through biomarker) Vaidya VS, Ramirez V, Ichimura T, others (2010). “Kidney injury molecule-1 outperforms traditional biomarkers of kidney injury in preclinical biomarker qualification studies.” Nature Biotechnology, 28(5), 478–485. doi:10.1038/nbt.1623 . (KIM-1 biomarker qualification; pass-through) Portilla D, Dent C, Sugaya T, others (2008). “Urinary liver-type fatty acid-binding protein as a biomarker of acute kidney injury.” Kidney International, 73(4), 465–472. doi:10.1038/sj.ki.5002721 . (L-FABP as AKI biomarker; pass-through)

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)
#> renal_markers(): reading input 'df' — 1 rows × 5 variables
#> renal_markers(): col_map (5 columns — 5 specified)
#>   creatinine        ->  'Cr'
#>   age               ->  'Age'
#>   sex               ->  'Sex'
#>   race              ->  'Race'
#>   BUN               ->  'BUN'
#> renal_markers(): optional inputs
#>   missing:  cystatin_C, urea_serum, creatinine_urine, urea_urine, NGAL, KIM1, NAG, beta2_micro, IL18, L_FABP
#>   indices -> NA:
#>   eGFR_cys -> NA  [missing: cystatin_C]
#>   eGFR_combined -> NA  [missing: cystatin_C]
#>   FE_Urea -> NA  [missing: urea_serum, creatinine_urine, urea_urine]
#> renal_markers(): computing markers:
#>   eGFR_cr        [creatinine, age, sex, race]
#>   eGFR_cys       NA [cystatin_C missing]
#>   eGFR_combined  NA [cystatin_C missing]
#>   BUN_Cr_ratio   [BUN, creatinine]
#>   FE_Urea        NA [urea/urine inputs missing]
#> renal_markers(): results: eGFR_cr 1/1, eGFR_cys 0/1, eGFR_combined 0/1, BUN_Cr_ratio 1/1, FE_Urea 0/1, NGAL 0/1, KIM1 0/1, NAG 0/1, Beta2Micro 0/1, IL18 0/1, L_FABP 0/1
#> # A tibble: 1 × 11
#>   eGFR_cr eGFR_cys eGFR_combined BUN_Cr_ratio FE_Urea  NGAL  KIM1   NAG
#>     <dbl>    <dbl>         <dbl>        <dbl>   <dbl> <dbl> <dbl> <dbl>
#> 1    93.7       NA            NA           14      NA    NA    NA    NA
#> # ℹ 3 more variables: Beta2Micro <dbl>, IL18 <dbl>, L_FABP <dbl>