Urine Markers

Scope

Compute urine-only renal and tubular markers: UACR, KDIGO albuminuria stage (A1–A3), microalbuminuria flag, UPCR (if protein provided), urine Na/K ratio (if electrolytes provided), and creatinine-normalized tubular markers (NGAL, KIM1, NAG, Beta2Micro, A1Micro, IL18, L_FABP). Includes mapping validation, NA policies, optional extreme screening/capping, and safe division with consolidated zero-denominator warnings. No unit conversion is applied.

When to use this

You have urine albumin and creatinine (mg/L, mg/dL) and want UACR and albuminuria staging.
You also have urine protein, Na/K, or tubular markers and need creatinine-normalized ratios.
You want robust NA/extreme handling with safe divisions to avoid Inf/NaN.

What you need (inputs & options)

Argument	Purpose / Options	Notes
data	Data frame/tibble with urine assays	Columns mapped by name (defaults assume same names)
na_action	Missing-data policy for required inputs	“keep” (default), “omit”, “error”
na_warn_prop	Proportion threshold for high-missingness diagnostics	Default 0.2 (shown in debug/verbose)
verbose	Emit progress and completion summaries	Default FALSE

Required columns: urine_albumin (mg/L), urine_creatinine (mg/dL).

Optional columns: urine_protein (mg/L), urine_Na (mmol/L), urine_K (mmol/L), NGAL, KIM1, NAG, beta2_micro (Beta2Micro output), a1_micro (A1Micro output), IL18, L_FABP.

Units: No conversion. Ensure albumin/protein mg/L, creatinine mg/dL, Na/K mmol/L; tubular marker units consistent across markers.

Handling and expectations

Validation & coercion: required columns must exist; numeric coercion with warnings if NAs introduced; non-finite set to NA.
Missingness: keep propagates NA; omit drops rows with required NA; error aborts if required inputs contain NA.
High-missing diagnostics: controlled by na_warn_prop; shown when verbose (or debug) is enabled.
Safe division: zero/invalid denominators set outputs to NA with a consolidated warning.
Albuminuria staging: A1 < 30 mg/g, A2 30–300 mg/g, A3 > 300 mg/g; microalbuminuria flag is micro for 30–300 mg/g, else normal.
Empty result: if na_action = "omit" drops all rows, returns a zero-row tibble with expected columns.

Outputs

UACR, albuminuria_stage (A1/A2/A3), microalbuminuria (normal/micro), UPCR (if urine_protein present), U_Na_K_ratio (if Na & K present), NGAL_per_gCr, KIM1_per_gCr, NAG_per_gCr, Beta2Micro_per_gCr, A1Micro_per_gCr, IL18_per_gCr, L_FABP_per_gCr.
NA arises from missing/invalid inputs, zero denominators, or dropped rows under omit.

Worked example 1: Standard inputs, keep NAs

library(HealthMarkers)
library(tibble)

df <- tibble::tibble(
  urine_albumin = c(25, 450, NA),      # mg/L
  urine_creatinine = c(1.0, 0.8, 0.5), # mg/dL
  urine_protein = c(120, NA, 90),      # mg/L
  urine_Na = c(100, 80, 90),
  urine_K = c(40, 30, 0),
  NGAL = c(15, 40, 20)
)

urine_markers(
  data = df,
  na_action = "keep",
  verbose = TRUE
)
#> # A tibble: 3 × 12
#>    UACR albuminuria_stage microalbuminuria  UPCR U_Na_K_ratio NGAL_per_gCr
#>   <dbl> <fct>             <fct>            <dbl>        <dbl>        <dbl>
#> 1  2500 A3                normal           12000         2.5          1500
#> 2 56250 A3                normal              NA         2.67         5000
#> 3    NA NA                normal           18000        NA            4000
#> # ℹ 6 more variables: KIM1_per_gCr <dbl>, NAG_per_gCr <dbl>,
#> #   Beta2Micro_per_gCr <dbl>, A1Micro_per_gCr <dbl>, IL18_per_gCr <dbl>,
#> #   L_FABP_per_gCr <dbl>

Interpretation: Computes UACR, staging, micro flag, UPCR, U_Na_K_ratio, and NGAL_per_gCr where inputs exist; NA propagates for missing or zero denominators (e.g., urine_K = 0).

Worked example 2: Drop incomplete rows

df2 <- tibble::tibble(
  urine_albumin = c(20, 120000),    # extreme albumin; pre-filter
  urine_creatinine = c(1.2, 0.005), # very low creatinine; pre-filter
  urine_protein = c(80, 90000),
  urine_Na = c(90, 500),
  urine_K = c(35, 210),
  NGAL = c(10, 200000)
)

# Pre-filter implausible values before calling
df2$urine_albumin[df2$urine_albumin > 100000] <- NA
df2$NGAL[df2$NGAL > 100000] <- NA

urine_markers(
  data = df2,
  na_action = "omit",
  verbose = TRUE
)
#> # A tibble: 1 × 12
#>    UACR albuminuria_stage microalbuminuria  UPCR U_Na_K_ratio NGAL_per_gCr
#>   <dbl> <fct>             <fct>            <dbl>        <dbl>        <dbl>
#> 1 1667. A3                normal           6667.         2.57         833.
#> # ℹ 6 more variables: KIM1_per_gCr <dbl>, NAG_per_gCr <dbl>,
#> #   Beta2Micro_per_gCr <dbl>, A1Micro_per_gCr <dbl>, IL18_per_gCr <dbl>,
#> #   L_FABP_per_gCr <dbl>

Interpretation: Implausible values are set to NA before calling; incomplete rows are then dropped; zero-denominator warnings list counts.

Troubleshooting & common pitfalls

Units: ensure albumin/protein mg/L, creatinine mg/dL; Na/K mmol/L; tubular marker units consistent across markers.
Missing columns: required columns must be present; optional markers only emit outputs when supplied.
Zero denominators: check urine_creatinine, urine_K; warnings list how many cases; outputs set to NA.
All NA outputs: often due to missing required inputs, zero denominators, or aggressive na_action = "omit".

Verbose diagnostics

old_opt <- options(healthmarkers.verbose = "inform")
urine_markers(
  data = tibble::tibble(urine_albumin = 30, urine_creatinine = 2),
  verbose = TRUE
)
#> urine_markers(): reading input 'data' — 1 rows × 2 variables
#> urine_markers(): col_map (2 columns — 2 inferred from data)
#>   urine_albumin     ->  'urine_albumin'    (inferred)
#>   urine_creatinine  ->  'urine_creatinine'    (inferred)
#> urine_markers(): computing markers:
#>   UACR, albuminuria_stage, microalbuminuria [urine_albumin, urine_creatinine]
#>   UPCR [urine_protein, urine_creatinine]
#>   U_Na_K_ratio [urine_Na, urine_K]
#>   NGAL/KIM1/NAG/Beta2Micro/A1Micro/IL18/L_FABP per gCr [optional]
#> urine_markers(): results: UACR 1/1, albuminuria_stage 1/1, microalbuminuria 1/1, UPCR 0/1, U_Na_K_ratio 0/1, NGAL_per_gCr 0/1, KIM1_per_gCr 0/1, NAG_per_gCr 0/1, Beta2Micro_per_gCr 0/1, A1Micro_per_gCr 0/1, IL18_per_gCr 0/1, L_FABP_per_gCr 0/1
#> # A tibble: 1 × 12
#>    UACR albuminuria_stage microalbuminuria  UPCR U_Na_K_ratio NGAL_per_gCr
#>   <dbl> <fct>             <fct>            <dbl>        <dbl>        <dbl>
#> 1  1500 A3                normal              NA           NA           NA
#> # ℹ 6 more variables: KIM1_per_gCr <dbl>, NAG_per_gCr <dbl>,
#> #   Beta2Micro_per_gCr <dbl>, A1Micro_per_gCr <dbl>, IL18_per_gCr <dbl>,
#> #   L_FABP_per_gCr <dbl>
options(old_opt)

Column recognition

Run hm_col_report(your_data) to check which analyte columns are auto-detected before building your col_map. See the Multi-Biobank Compatibility article for recognised synonyms across major biobanks.

hm_col_report(your_data)

Tips for best results

Use na_action = "omit" when downstream analyses need complete cases; keep for exploratory review.
Monitor zero-denominator warnings—extremely low creatinine or K values will blank ratios and per-gCr markers.

Validation notes

UACR = (urine_albumin / urine_creatinine) * 1000 (mg/g); UPCR analogous when protein present.
U_Na_K_ratio = urine_Na / urine_K.
Tubular markers per g creatinine: marker / (urine_creatinine * 0.01) where denominator is g/L.
Divisions are safe: non-finite/zero denominators yield NA with a consolidated warning.