Help for package kfre

Type:

Package

Title:

Kidney Failure Risk Equation (KFRE) Tools

Version:

0.0.2

Description:

Implements the Kidney Failure Risk Equation (KFRE; Tangri and colleagues (2011) <doi:10.1001/jama.2011.451>; Tangri and colleagues (2016) <doi:10.1001/jama.2015.18202>) to compute 2- and 5-year kidney failure risk using 4-, 6-, and 8-variable models. Includes helpers to append risk columns to data frames, classify chronic kidney disease (CKD) stages and end-stage renal disease (ESRD) outcomes, and evaluate and plot model performance.

License:

MIT + file LICENSE

URL:

https://github.com/lshpaner/kfre_r, https://lshpaner.github.io/kfre_r/

BugReports:

https://github.com/lshpaner/kfre_r/issues

Depends:

R (≥ 3.6)

Imports:

ggplot2, grDevices, R6

Suggests:

devtools, knitr, readxl, rmarkdown, rprojroot, spelling, svglite, testthat (≥ 3.0.0)

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.3.2

VignetteBuilder:

knitr

Language:

en-US

NeedsCompilation:

Packaged:

2025-08-22 22:25:34 UTC; lshpaner

Author:

Leonid Shpaner

[aut, cre] (URL: https://www.leonshpaner.com)

Maintainer:

Leonid Shpaner <lshpaner@ucla.edu>

Repository:

CRAN

Date/Publication:

2025-08-28 07:40:12 UTC

kfre: KFRE Risk Prediction Tools (R)

Description

Implements the Kidney Failure Risk Equation (KFRE; Tangri et al.) to compute 2- and 5-year risk (4-, 6-, and 8-variable models), add risk columns to data frames, classify CKD stages/ESRD outcomes, and evaluate & plot performance.

Key functions

risk_pred_core()
add_kfre_risk_col()
eval_kfre_metrics(), plot_kfre_metrics()
class_esrd_outcome(), class_ckd_stages()

Author(s)

Leonid Shpaner lshpaner@ucla.edu (ORCID)
https://github.com/lshpaner/kfre_r
https://www.leonshpaner.com/

Add KFRE risk columns to a data frame

Description

Adds KFRE risk columns for selected model sizes and horizons using the 4, 6, or 8 variable equations.

Usage

add_kfre_risk_col(
  df,
  age_col = NULL,
  sex_col = NULL,
  eGFR_col = NULL,
  uACR_col = NULL,
  dm_col = NULL,
  htn_col = NULL,
  albumin_col = NULL,
  phosphorous_col = NULL,
  bicarbonate_col = NULL,
  calcium_col = NULL,
  num_vars = 8,
  years = c(2, 5),
  is_north_american = FALSE,
  copy = TRUE,
  precision = NULL
)

Arguments

df

Data frame with predictor columns.

age_col

Column name for age.

sex_col

Column name for sex, text or integer accepted.

eGFR_col

Column name for eGFR, mL/min/1.73 m^2.

uACR_col

Column name for uACR, mg/g.

dm_col

Optional column name for diabetes indicator.

htn_col

Optional column name for hypertension indicator.

albumin_col

Optional column name for serum albumin, g/dL.

phosphorous_col

Optional column name for serum phosphorus, mg/dL.

bicarbonate_col

Optional column name for bicarbonate, mmol/L.

calcium_col

Optional column name for calcium, mg/dL.

num_vars

Integer or vector, one of 4, 6, 8.

years

Integer or vector, any of 2, 5.

is_north_american

Logical, use North American calibration.

copy

Logical, if TRUE work on a copy of df.

precision

Optional integer, digits to round probabilities.

Value

The input data frame with added ⁠kfre_<n>var_<y>year⁠ columns.

References

Tangri, N., Stevens, L. A., Griffith, J., Tighiouart, H., Djurdjev, O., Naimark, D., Levin, A., & Levey, A. S. (2011). A predictive model for progression of chronic kidney disease to kidney failure. JAMA, 305(15), 1553–1559. doi:10.1001/jama.2011.451

Tangri, N., Grams, M. E., Levey, A. S., et al. (2016). Multinational assessment of the accuracy of the Kidney Failure Risk Equation in people with chronic kidney disease. JAMA, 315(2), 164–174. doi:10.1001/jama.2015.18202

Examples

df <- data.frame(
  age = 60L, sex = 1L, eGFR = 30, uACR = 500,
  dm = 1L, htn = 0L, albumin = 40,
  phosphorous = 1.1, bicarbonate = 24, calcium = 9.2
)

add_kfre_risk_col(
  df,
  age_col = "age", sex_col = "sex",
  eGFR_col = "eGFR", uACR_col = "uACR",
  num_vars = 4, years = 2
)

Apply precision (round helper)

Description

Simple wrapper around base round() used by tests and examples.

Usage

apply_precision(x, n = NULL)

Arguments

x

Numeric vector.

n

Integer number of digits to keep. If NULL, return x unchanged.

Value

Numeric vector rounded to n.

Label CKD stages or ESRD outcomes.

Description

Label CKD stages or ESRD outcomes.

Usage

class_ckd_stages(
  df,
  egfr_col = "eGFR",
  stage_col = NULL,
  combined_stage_col = NULL
)

Arguments

df

Data frame input.

egfr_col

Column name for eGFR, mL/min/1.73 m^2.

stage_col

Output column name for detailed CKD stages.

combined_stage_col

Output column for combined stages 3 to 5.

Value

The modified data frame with added label columns.

Examples

df <- data.frame(eGFR = c(92, 58, 42, 28, 12))
class_ckd_stages(df, egfr_col = "eGFR")

Label CKD stages or ESRD outcomes.

Description

Label CKD stages or ESRD outcomes.

Usage

class_esrd_outcome(
  df,
  col,
  years,
  duration_col,
  prefix = NULL,
  create_years_col = TRUE
)

Arguments

df

Data frame with an eGFR column.

col

Column name with ESRD event indicator, 0 or 1.

years

Integer horizon, 2 or 5.

duration_col

Column name with follow up time in days.

prefix

Optional prefix for the derived outcome column.

create_years_col

Logical, add a ⁠<years>_year_outcome⁠ column.

Value

The modified data frame with added label columns.

Examples

df <- data.frame(
  eGFR = c(90, 45, 25, 10),
  esrd = c(0, 0, 1, 0),
  followup_days = c(365, 800, 500, 1200)
)
class_esrd_outcome(
  df,
  col = "esrd",
  years = 2,
  duration_col = "followup_days"
)

Summarize KFRE performance metrics by model size and horizon

Description

Builds a wide table of Precision, Sensitivity, Specificity, AUC, Brier, and Average Precision for specified KFRE variants at 2 and 5 years.

Usage

eval_kfre_metrics(df, n_var_list, outcome_years = 2, decimal_places = 6)

Arguments

df

Data frame with truth and probability columns.

n_var_list

Integer vector of models to evaluate, any of 4, 6, 8.

outcome_years

Integer vector of horizons, any of 2, 5.

decimal_places

Integer digits to round displayed values.

Value

Data frame of metrics with one column per model-horizon.

Perform unit and code conversions used by KFRE helpers.

Description

Perform unit and code conversions used by KFRE helpers.

Usage

perform_conversions(
  df,
  reverse = FALSE,
  convert_all = FALSE,
  upcr_col = NULL,
  calcium_col = NULL,
  phosphate_col = NULL,
  albumin_col = NULL
)

Arguments

df

Data frame with source columns to convert.

reverse

Logical, reverse the conversion if TRUE.

convert_all

Logical, convert all known columns if TRUE.

upcr_col

Column name for urine protein creatinine ratio.

calcium_col

Optional column for serum calcium, mg/dL.

phosphate_col

Optional column for serum phosphorus, mg/dL.

albumin_col

Optional column for serum albumin, g/dL.

Value

A data frame with converted columns.

Examples

df <- data.frame(
  upcr = c(100, 400),         # mg/g (or g/g scaled accordingly)
  albumin = c(40, 38),        # g/L
  phosphorous = c(1.1, 1.3),  # mmol/L
  calcium = c(9.2, 8.8)       # mg/dL
)
perform_conversions(df)

Plot ROC and Precision Recall curves for KFRE variants

Description

Draws ROC and PR curves for the selected models and horizons. When mode is "both", returns a list of ggplot objects. Otherwise, draws the plots and returns NULL invisibly.

Arguments

df

Data frame containing model probabilities and outcomes.

num_vars

Integer vector, KFRE model sizes to plot, any of 4, 6, 8.

fig_size

Numeric length 2, plot device width and height.

mode

Character, "both" to return plots, otherwise draw only.

image_path_png

Optional directory to save PNGs.

image_path_svg

Optional directory to save SVGs.

image_prefix

Optional filename prefix.

bbox_inches

Character, passed through when saving.

plot_type

Character, which plots to render.

save_plots

Logical, save plots to disk if TRUE.

show_years

Integer vector, horizons to show, any of 2, 5.

plot_combinations

Logical, if TRUE draw pairwise overlays.

show_subplots

Logical, arrange subplots when TRUE.

decimal_places

Integer digits for annotations.

open_new_device

Logical, open device before plotting.

Value

List of ggplot objects when mode == "both", else NULL.

KFRE risk prediction for a single person

Description

Computes the Kidney Failure Risk Equation probability at 2 or 5 years.

Usage

risk_pred_core(
  age,
  sex,
  eGFR,
  uACR,
  is_north_american,
  dm = NULL,
  htn = NULL,
  albumin = NULL,
  phosphorous = NULL,
  bicarbonate = NULL,
  calcium = NULL,
  years = 2
)

Arguments

age

Numeric age in years.

sex

Integer sex indicator, 1 for male, 0 for female.

eGFR

Estimated glomerular filtration rate, mL/min/1.73 \text{m}^{2}.

uACR

Urine albumin to creatinine ratio, mg/g.

is_north_american

Logical, patient from a North American cohort.

dm

Optional integer diabetes indicator, 1 yes, 0 no.

htn

Optional integer hypertension indicator, 1 yes, 0 no.

albumin

Optional serum albumin, g/dL, required for 8 variable model.

phosphorous

Optional serum phosphorus, mg/dL, 8 variable model.

bicarbonate

Optional serum bicarbonate, mmol/L, 8 variable model.

calcium

Optional serum calcium, mg/dL, 8 variable model.

years

Integer, prediction horizon, 2 or 5.

Value

Numeric probability between 0 and 1.

References

Examples

risk_pred_core(60, 1, 45, 120, TRUE, dm = 1, htn = 1, years = 2)

Convert UPCR to UACR with clinical covariates

Description

Implements the equation reported by Sumida et al. for converting urine protein–creatinine ratio to urine albumin–creatinine ratio, with adjustments for sex, diabetes, and hypertension.

Usage

upcr_uacr(
  df,
  sex_col,
  diabetes_col,
  hypertension_col,
  upcr_col,
  female_str = "female"
)

Arguments

df

A data.frame containing the required columns.

sex_col

Column name with sex labels, character. Example: "sex".

diabetes_col

Column name with diabetes indicator, 0 or 1, or logical. Example: "diabetes".

hypertension_col

Column name with hypertension indicator, 0 or 1, or logical. Example: "hypertension".

upcr_col

Column name with UPCR values. Units should match those used to derive the model in Sumida et al. (mg/g). If your data use different units, convert before calling.

female_str

String that denotes female in sex_col. Default is "female".

Details

The function applies a piecewise log transformation of UPCR with cut points at 50 and 500, and adds covariate adjustments for sex, diabetes, and hypertension, then exponentiates to return UACR. Valid rows require non missing diabetes and hypertension indicators. Sex is mapped to an indicator using female_str.

Value

A numeric vector of UACR values, length nrow(df). Non valid rows return NA_real_.

References

Sumida, K., Nadkarni, G. N., Grams, M. E., Sang, Y., Ballew, S. H., Coresh, J., Matsushita, K., Surapaneni, A., Brunskill, N., Chadban, S. J., Chang, A. R., Cirillo, M., Daratha, K. B., Gansevoort, R. T., Garg, A. X., Iacoviello, L., Kayama, T., Konta, T., Kovesdy, C. P., Lash, J., Lee, B. J., Major, R. W., Metzger, M., Miura, K., Naimark, D. M. J., Nelson, R. G., Sawhney, S., Stempniewicz, N., Tang, M., Townsend, R. R., Traynor, J. P., Valdivielso, J. M., Wetzels, J., Polkinghorne, K. R., and Heerspink, H. J. L. (2020). Conversion of urine protein-creatinine ratio or urine dipstick protein to urine albumin-creatinine ratio for use in chronic kidney disease screening and prognosis. Annals of Internal Medicine, 173(6), 426-435. doi:10.7326/M20-0529

Examples

df <- data.frame(
  sex = c("female", "male"),
  diabetes = c(1, 0),
  hypertension = c(0, 1),
  upcr = c(100, 400)  # mg/g (or same ratio units)
)
upcr_uacr(df, "sex", "diabetes", "hypertension", "upcr")

kfre: KFRE Risk Prediction Tools (R)

Description

Key functions

Author(s)

See Also

Add KFRE risk columns to a data frame

Description

Usage

Arguments

Value

References

Examples

Apply precision (round helper)

Description

Usage

Arguments

Value

Label CKD stages or ESRD outcomes.

Description

Usage

Arguments

Value

Examples

Label CKD stages or ESRD outcomes.

Description

Usage

Arguments

Value

Examples

Summarize KFRE performance metrics by model size and horizon

Description

Usage

Arguments

Value

Perform unit and code conversions used by KFRE helpers.

Description

Usage

Arguments

Value

Examples

Plot ROC and Precision Recall curves for KFRE variants

Description

Arguments

Value

KFRE risk prediction for a single person

Description

Usage

Arguments

Value

References

Examples

Convert UPCR to UACR with clinical covariates

Description

Usage

Arguments

Details

Value

References

Examples