Skip to contents

Kidney failure risk (KFRE)

Source: vignettes/articles/kidney_kfre.Rmd
kidney_kfre.Rmd

Scope

4-variable Kidney Failure Risk Equation (KFRE) for 2- and 5-year ESKD risk. Includes NA policies, high-missingness warnings, optional extreme scanning with warn/cap/NA/error behaviors, and verbose summaries. Units: age (years), sex coded 1=male/2=female, eGFR (mL/min/1.73 m^2), UACR (mg/g); no unit conversion is performed.

Load packages and demo data 

library(HealthMarkers)
library(tibble)

df <- tibble::tibble(
  age  = c(65, 72, 80),
  sex  = c(1, 2, 1),
  eGFR = c(45, 22, 10),
  UACR = c(300, 1200, 8000)
)

Column map (required) 

col_map <- list(age = "age", sex = "sex", eGFR = "eGFR", UACR = "UACR")

Core calculation

Default na_action = "keep": missing inputs propagate to NA risks; no extreme checks.

kfre_default <- kidney_failure_risk(
  data = df,
  col_map = col_map,
  na_action = "keep",
  check_extreme = FALSE,
  verbose = FALSE
)

kfre_default
#> # A tibble: 3 × 2
#>   KFRE_2yr KFRE_5yr
#>      <dbl>    <dbl>
#> 1    0.329    0.523
#> 2    0.536    0.759
#> 3    0.986    1.000

Extreme screening and capping

Enable range checks and cap out-of-range inputs.

kfre_cap <- kidney_failure_risk(
  data = df,
  col_map = col_map,
  na_action = "warn",
  check_extreme = TRUE,
  extreme_action = "cap",
  verbose = TRUE
)

kfre_cap
#> # A tibble: 3 × 2
#>   KFRE_2yr KFRE_5yr
#>      <dbl>    <dbl>
#> 1    0.329    0.523
#> 2    0.536    0.759
#> 3    0.986    1.000

extreme_action = "warn" only warns; error aborts; NA blanks flagged values before calculation.

Missing data handling

keep propagates NA risks; omit drops rows with missing required inputs; error stops on missingness.

df_na <- df
df_na$eGFR[2] <- NA

keep_out <- kidney_failure_risk(df_na, col_map, na_action = "keep")
omit_out <- kidney_failure_risk(df_na, col_map, na_action = "omit")

list(keep_rows = nrow(keep_out), omit_rows = nrow(omit_out))
#> $keep_rows
#> [1] 3
#> 
#> $omit_rows
#> [1] 2

Expectations

  • All four predictors must be mapped and present; sex must be 1/2.
  • Inputs must be numeric; non-finite become NA and may propagate depending on na_action.
  • Extreme defaults: age 18–120, eGFR 1–200, UACR 0.1–10000 mg/g. Adjust via extreme_rules if needed.
  • Output: tibble with KFRE_2yr, KFRE_5yr; row count follows na_action and any row filtering you apply.

Verbose diagnostics 

old_opt <- options(healthmarkers.verbose = "inform")
kidney_failure_risk(
  data    = df,
  col_map = col_map,
  verbose = TRUE
)
#> kidney_failure_risk(): preparing inputs
#> kidney_failure_risk(): column map: age -> 'age', sex -> 'sex', eGFR -> 'eGFR', UACR -> 'UACR'
#> kidney_failure_risk(): results: KFRE_2yr 3/3, KFRE_5yr 3/3
#> # A tibble: 3 × 2
#>   KFRE_2yr KFRE_5yr
#>      <dbl>    <dbl>
#> 1    0.329    0.523
#> 2    0.536    0.759
#> 3    0.986    1.000
options(old_opt)

Tips

  • Check units before running (e.g., UACR mg/g vs mg/mmol); convert upstream if needed.
  • Use na_action = "error" for strict QA; warn to surface high missingness while retaining rows.
  • Tighten extreme bounds for your cohort; keep verbose = TRUE while setting them.